Replace profile

Writes the caller org's tax profile — its Form W-9, or its Form W-8BEN or W-8BEN-E when it is a foreign person — and answers it, every number masked.

PUT /v1/tax/profile

Tax → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/tax/profile`
Method	`PUT`
Operation	`put_tax_profile`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Writes the caller org's tax profile — its Form W-9, or its Form W-8BEN or W-8BEN-E when it is a foreign person — and answers it, every number masked. Org admins only.

A U.S. TIN is validated before it is kept — nine digits; an EIN's prefix must be one the IRS assigns; an SSN never begins 000, 666 or 9xx and has no zero group or serial; an ITIN's middle digits are in the IRS ranges. A foreign TIN is the issuing jurisdiction's and is checked only for its characters. Every number is sealed under this org's own data key before it is written. Validating the FORMAT is all this does: whether the IRS has the number on file under this name is IRS TIN Matching, which a payer runs through IRS e-Services.

A W-8 is refused where the form itself says it is the wrong one: a U.S. citizen, a U.S. permanent residence or an entity organized in the United States is a U.S. person and files a W-9. A treaty claim needs a U.S. or foreign TIN on the form (Instructions for Form W-8BEN, line 5; for Form W-8BEN-E, line 8), and names the country of the permanent residence address.

Changing any fact on the form makes a new version, and the certification no longer covers it: certify again. For a W-8 that is the "change in circumstances" the instructions end its validity on. Changing only the consent does not.

Request

34 fields, body application/json (required).

Field	In	Type	Required	Description
`address`	body	tax.Address	—
`address.city`	body	string	—	City is the city or town.
`address.country`	body	string	—	Country is ISO 3166-1 alpha-2; "US" when absent.
`address.line1`	body	string	—	Line1 is the number, street, and apartment or suite.
`address.line2`	body	string	—	Line2 continues the street address, when there is more of it.
`address.state`	body	string	—	State is the two-letter state or territory code.
`address.zip`	body	string	—	ZIP is five or nine digits.
`businessName`	body	string	—	BusinessName is line 2, when it differs from line 1.
`classification`	body	string	—	Classification is W-9 line 3a: individual, c_corp, s_corp, partnership, trust_estate, llc_c, llc_s or llc_p.
`electronicConsent`	body	boolean	—	ElectronicConsent gives (true) or withdraws (false) consent to receive 1099s in the Hanzo inbox, against the disclosure every profile answers with.
`exemptPayee`	body	string	—	ExemptPayee is the exempt payee code, 1–13.
`fatca`	body	string	—	FATCA is the FATCA exemption code, A–M.
`foreignOwners`	body	boolean	—	ForeignOwners is line 3b; only a partnership, trust/estate or llc_p may set it.
`foreignTin`	body	string	—	ForeignTIN is a W-8's foreign tax identifying number (W-8BEN line 6a, W-8BEN-E line 9b), as the jurisdiction of residence issues it.
`form`	body	string	—	Form is w9 (a U.S. person), w8ben (a foreign individual) or w8bene (a foreign entity).
`name`	body	string	—	Name is line 1: the name on the income tax return, or the foreign individual's or organization's name.
`phone`	body	string	—	Phone is printed on the 1099s this org files as payer.
`tin`	body	string	—	TIN is W-9 Part I, or a W-8's U.S. TIN (W-8BEN line 5, W-8BEN-E line 8), digits with or without hyphens.
`tinType`	body	string	—	TINType is ssn (an SSN or ITIN) or ein.
`w8`	body	tax.W8	—
`w8.birth`	body	string	—	Birth is W-8BEN line 8, the individual's date of birth, YYYY-MM-DD.
`w8.capacity`	body	string	—	Capacity is the capacity in which the signer signs for the beneficial owner — "Director", "Authorized officer".
`w8.chapter3`	body	string	—	Chapter3 is W-8BEN-E line 4.
`w8.chapter4`	body	string	—	Chapter4 is W-8BEN-E line 5, the FATCA status.
`w8.country`	body	string	—	Country is line 2: the country of citizenship (W-8BEN) or of incorporation or organization (W-8BEN-E), ISO 3166-1 alpha-2.
`w8.giin`	body	string	—	GIIN is W-8BEN-E line 9a, when the chapter 4 status carries one.
`w8.noForeignTin`	body	boolean	—	NoForeignTIN is W-8BEN line 6b / W-8BEN-E line 9b's alternative: the jurisdiction of residence does not require or issue a foreign TIN.
`w8.treaty`	body	tax.Treaty	—
`w8.treaty.article`	body	string	—	Article is the treaty article and paragraph claimed, e.g. "12(2)".
`w8.treaty.conditions`	body	string	—	Conditions is the explanation the form asks for: the conditions of the article the beneficial owner meets.
`w8.treaty.country`	body	string	—	Country is the treaty country the beneficial owner is resident in.
`w8.treaty.income`	body	string	—	Income is the type of income the claim covers: services, rents, royalties or other.
`w8.treaty.lob`	body	string	—	LOB is W-8BEN-E line 14b: the treaty's limitation on benefits provision the entity meets.
`w8.treaty.rateBps`	body	integer (int64)	—	RateBps is the claimed withholding rate in basis points: 0 is exempt, 1000 is 10%.

Response

Status	Body	Meaning
`200`	tax.Profile	ok
`default`	problem-details	refused

200 body — 49 fields.

Field	In	Type	Always	Description
`address`	body	tax.Address	—
`address.city`	body	string	—	City is the city or town.
`address.country`	body	string	—	Country is ISO 3166-1 alpha-2; "US" when absent.
`address.line1`	body	string	—	Line1 is the number, street, and apartment or suite.
`address.line2`	body	string	—	Line2 continues the street address, when there is more of it.
`address.state`	body	string	—	State is the two-letter state or territory code.
`address.zip`	body	string	—	ZIP is five or nine digits.
`businessName`	body	string	—	BusinessName is line 2: the business or disregarded entity name.
`certification`	body	tax.Certification	—
`certification.by`	body	string	—	By is who signed it: the IAM user legal recorded completing the signature.
`certification.document`	body	string	—	Document is the /v1/legal document that carries the signature.
`certification.signed`	body	integer (int64)	—	Signed is when legal reported the document signed, unix seconds.
`certification.signer`	body	string	—	Signer is the IAM user the signature was opened for — the admin who asked.
`certification.status`	body	string	—	Status is none, pending (a signature is open) or certified.
`certification.version`	body	integer (int64)	—	Version is the profile version the signature covers.
`classification`	body	string	—	Classification is line 3a.
`consent`	body	tax.Consent	—
`consent.at`	body	integer (int64)	—	At is when the consent was given or withdrawn, unix seconds.
`consent.by`	body	string	—	By is the IAM user who gave or withdrew it.
`consent.electronic`	body	boolean	—	Electronic is true while the consent stands.
`disclosure`	body	string	—	Disclosure is the electronic-delivery disclosure the consent is given against.
`exemptPayee`	body	string	—	ExemptPayee is line 4's exempt payee code, 1–13.
`expires`	body	integer (int64)	—	Expires is when a certified W-8 stops being valid, unix seconds: the last day of the third calendar year after the year it was signed.
`fatca`	body	string	—	FATCA is line 4's FATCA exemption code, A–M.
`foreignOwners`	body	boolean	—	ForeignOwners is line 3b: a flow-through entity with foreign partners, owners or beneficiaries.
`foreignTin`	body	string	—	ForeignTIN is a W-8's foreign tax identifying number, masked.
`form`	body	string	—	Form is w9, w8ben or w8bene.
`name`	body	string	—	Name is line 1: the name on the income tax return, or of the foreign individual or organization that is the beneficial owner.
`phone`	body	string	—	Phone is the number a 1099 this org files as PAYER prints for it.
`tin`	body	string	—	TIN is Part I, masked to its last four digits.
`tinType`	body	string	—	TINType is which Part I box: ssn (an SSN or ITIN) or ein.
`updatedAt`	body	integer (int64)	—	UpdatedAt is when the profile last changed, unix seconds.
`valid`	body	boolean	—	Valid is whether the form establishes what it certifies today — for a W-8, certified for its current version and not expired; for a W-9, a TIN on file.
`version`	body	integer (int64)	—	Version counts the W-9's revisions; a certification covers exactly one.
`w8`	body	tax.W8	—
`w8.birth`	body	string	—	Birth is W-8BEN line 8, the individual's date of birth, YYYY-MM-DD.
`w8.capacity`	body	string	—	Capacity is the capacity in which the signer signs for the beneficial owner — "Director", "Authorized officer".
`w8.chapter3`	body	string	—	Chapter3 is W-8BEN-E line 4.
`w8.chapter4`	body	string	—	Chapter4 is W-8BEN-E line 5, the FATCA status.
`w8.country`	body	string	—	Country is line 2: the country of citizenship (W-8BEN) or of incorporation or organization (W-8BEN-E), ISO 3166-1 alpha-2.
`w8.giin`	body	string	—	GIIN is W-8BEN-E line 9a, when the chapter 4 status carries one.
`w8.noForeignTin`	body	boolean	—	NoForeignTIN is W-8BEN line 6b / W-8BEN-E line 9b's alternative: the jurisdiction of residence does not require or issue a foreign TIN.
`w8.treaty`	body	tax.Treaty	—
`w8.treaty.article`	body	string	—	Article is the treaty article and paragraph claimed, e.g. "12(2)".
`w8.treaty.conditions`	body	string	—	Conditions is the explanation the form asks for: the conditions of the article the beneficial owner meets.
`w8.treaty.country`	body	string	—	Country is the treaty country the beneficial owner is resident in.
`w8.treaty.income`	body	string	—	Income is the type of income the claim covers: services, rents, royalties or other.
`w8.treaty.lob`	body	string	—	LOB is W-8BEN-E line 14b: the treaty's limitation on benefits provision the entity meets.
`w8.treaty.rateBps`	body	integer (int64)	—	RateBps is the claimed withholding rate in basis points: 0 is exempt, 1000 is 10%.

Failure carries the platform error shape — see Errors.

Examples

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

import { Configuration, TaxApi } from 'hanzoai';

const api = new TaxApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.putTaxProfile({ address: {"city":"<city>","country":"<country>","line1":"<line1>","line2":"<line2>"}, businessName: "<businessName>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import TaxApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = TaxApi(client).put_tax_profile(address={"city":"<city>","country":"<country>","line1":"<line1>","line2":"<line2>"}, business_name="<businessName>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.TaxAPI.PutTaxProfile(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, tax_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = tax_api::put_tax_profile(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.TaxApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new TaxApi(client).putTaxProfile();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X PUT https://api.hanzo.ai/v1/tax/profile \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "address": {
         "city": "<city>",
         "country": "<country>",
         "line1": "<line1>",
         "line2": "<line2>"
       },
       "businessName": "<businessName>"
     }'

MCP declares no tool for tax — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.

Tax API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page