List w9

Lists the caller org's W-9 relationships on both sides: the W-9s it asked its payees for, with where each stands, and the requests other orgs made for its own W-9.

GET /v1/tax/w9

Tax → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/tax/w9`
Method	`GET`
Operation	`get_tax_w9`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Lists the caller org's W-9 relationships on both sides: the W-9s it asked its payees for, with where each stands, and the requests other orgs made for its own W-9. Org admins only. No W-9 content is in the list; read one to see it.

Request

GET /v1/tax/w9 takes no parameters and no body — the credential is the whole request.

Response

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

200 body — 126 fields.

Field	In	Type	Always	Description
`asPayee`	body	tax.W9[]	—	AsPayee are the requests for the caller's own W-9.
`asPayee[].category`	body	string	—	Category is what the payer states it pays this payee for.
`asPayee[].decidedAt`	body	integer (int64)	—	DecidedAt is when the payee last granted, declined or revoked.
`asPayee[].id`	body	string	—	ID addresses the relationship on both sides.
`asPayee[].match`	body	tax.Match	—
`asPayee[].match.at`	body	integer (int64)	—	At is when the payer recorded it, unix seconds.
`asPayee[].match.by`	body	string	—	By is the admin who recorded it.
`asPayee[].match.result`	body	string	—	Result is what IRS TIN Matching answered: matched or mismatched.
`asPayee[].payee`	body	string	—	Payee is the org whose W-9 it is.
`asPayee[].payer`	body	string	—	Payer is the org that asked.
`asPayee[].profile`	body	tax.Profile	—
`asPayee[].profile.address`	body	tax.Address	—
`asPayee[].profile.address.city`	body	string	—	City is the city or town.
`asPayee[].profile.address.country`	body	string	—	Country is ISO 3166-1 alpha-2; "US" when absent.
`asPayee[].profile.address.line1`	body	string	—	Line1 is the number, street, and apartment or suite.
`asPayee[].profile.address.line2`	body	string	—	Line2 continues the street address, when there is more of it.
`asPayee[].profile.address.state`	body	string	—	State is the two-letter state or territory code.
`asPayee[].profile.address.zip`	body	string	—	ZIP is five or nine digits.
`asPayee[].profile.businessName`	body	string	—	BusinessName is line 2: the business or disregarded entity name.
`asPayee[].profile.certification`	body	tax.Certification	—
`asPayee[].profile.certification.by`	body	string	—	By is who signed it: the IAM user legal recorded completing the signature.
`asPayee[].profile.certification.document`	body	string	—	Document is the /v1/legal document that carries the signature.
`asPayee[].profile.certification.signed`	body	integer (int64)	—	Signed is when legal reported the document signed, unix seconds.
`asPayee[].profile.certification.signer`	body	string	—	Signer is the IAM user the signature was opened for — the admin who asked.
`asPayee[].profile.certification.status`	body	string	—	Status is none, pending (a signature is open) or certified.
`asPayee[].profile.certification.version`	body	integer (int64)	—	Version is the profile version the signature covers.
`asPayee[].profile.classification`	body	string	—	Classification is line 3a.
`asPayee[].profile.consent`	body	tax.Consent	—
`asPayee[].profile.consent.at`	body	integer (int64)	—	At is when the consent was given or withdrawn, unix seconds.
`asPayee[].profile.consent.by`	body	string	—	By is the IAM user who gave or withdrew it.
`asPayee[].profile.consent.electronic`	body	boolean	—	Electronic is true while the consent stands.
`asPayee[].profile.disclosure`	body	string	—	Disclosure is the electronic-delivery disclosure the consent is given against.
`asPayee[].profile.exemptPayee`	body	string	—	ExemptPayee is line 4's exempt payee code, 1–13.
`asPayee[].profile.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.
`asPayee[].profile.fatca`	body	string	—	FATCA is line 4's FATCA exemption code, A–M.
`asPayee[].profile.foreignOwners`	body	boolean	—	ForeignOwners is line 3b: a flow-through entity with foreign partners, owners or beneficiaries.
`asPayee[].profile.foreignTin`	body	string	—	ForeignTIN is a W-8's foreign tax identifying number, masked.
`asPayee[].profile.form`	body	string	—	Form is w9, w8ben or w8bene.
`asPayee[].profile.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.
`asPayee[].profile.phone`	body	string	—	Phone is the number a 1099 this org files as PAYER prints for it.
`asPayee[].profile.tin`	body	string	—	TIN is Part I, masked to its last four digits.
`asPayee[].profile.tinType`	body	string	—	TINType is which Part I box: ssn (an SSN or ITIN) or ein.
`asPayee[].profile.updatedAt`	body	integer (int64)	—	UpdatedAt is when the profile last changed, unix seconds.
`asPayee[].profile.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.
`asPayee[].profile.version`	body	integer (int64)	—	Version counts the W-9's revisions; a certification covers exactly one.
`asPayee[].profile.w8`	body	tax.W8	—
`asPayee[].profile.w8.birth`	body	string	—	Birth is W-8BEN line 8, the individual's date of birth, YYYY-MM-DD.
`asPayee[].profile.w8.capacity`	body	string	—	Capacity is the capacity in which the signer signs for the beneficial owner — "Director", "Authorized officer".
`asPayee[].profile.w8.chapter3`	body	string	—	Chapter3 is W-8BEN-E line 4.
`asPayee[].profile.w8.chapter4`	body	string	—	Chapter4 is W-8BEN-E line 5, the FATCA status.
`asPayee[].profile.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.
`asPayee[].profile.w8.giin`	body	string	—	GIIN is W-8BEN-E line 9a, when the chapter 4 status carries one.
`asPayee[].profile.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.
`asPayee[].profile.w8.treaty`	body	tax.Treaty	—
`asPayee[].profile.w8.treaty.article`	body	string	—	Article is the treaty article and paragraph claimed, e.g. "12(2)".
`asPayee[].profile.w8.treaty.conditions`	body	string	—	Conditions is the explanation the form asks for: the conditions of the article the beneficial owner meets.
`asPayee[].profile.w8.treaty.country`	body	string	—	Country is the treaty country the beneficial owner is resident in.
`asPayee[].profile.w8.treaty.income`	body	string	—	Income is the type of income the claim covers: services, rents, royalties or other.
`asPayee[].profile.w8.treaty.lob`	body	string	—	LOB is W-8BEN-E line 14b: the treaty's limitation on benefits provision the entity meets.
`asPayee[].profile.w8.treaty.rateBps`	body	integer (int64)	—	RateBps is the claimed withholding rate in basis points: 0 is exempt, 1000 is 10%.
`asPayee[].requestedAt`	body	integer (int64)	—	RequestedAt is when the payer asked, unix seconds.
`asPayee[].role`	body	string	—	Role is the caller's side of it: payer or payee.
`asPayee[].status`	body	string	—	Status is requested, granted, declined or revoked.
`asPayer`	body	tax.W9[]	—	AsPayer are the W-9s the caller asked for.
`asPayer[].category`	body	string	—	Category is what the payer states it pays this payee for.
`asPayer[].decidedAt`	body	integer (int64)	—	DecidedAt is when the payee last granted, declined or revoked.
`asPayer[].id`	body	string	—	ID addresses the relationship on both sides.
`asPayer[].match`	body	tax.Match	—
`asPayer[].match.at`	body	integer (int64)	—	At is when the payer recorded it, unix seconds.
`asPayer[].match.by`	body	string	—	By is the admin who recorded it.
`asPayer[].match.result`	body	string	—	Result is what IRS TIN Matching answered: matched or mismatched.
`asPayer[].payee`	body	string	—	Payee is the org whose W-9 it is.
`asPayer[].payer`	body	string	—	Payer is the org that asked.
`asPayer[].profile`	body	tax.Profile	—
`asPayer[].profile.address`	body	tax.Address	—
`asPayer[].profile.address.city`	body	string	—	City is the city or town.
`asPayer[].profile.address.country`	body	string	—	Country is ISO 3166-1 alpha-2; "US" when absent.
`asPayer[].profile.address.line1`	body	string	—	Line1 is the number, street, and apartment or suite.
`asPayer[].profile.address.line2`	body	string	—	Line2 continues the street address, when there is more of it.
`asPayer[].profile.address.state`	body	string	—	State is the two-letter state or territory code.
`asPayer[].profile.address.zip`	body	string	—	ZIP is five or nine digits.
`asPayer[].profile.businessName`	body	string	—	BusinessName is line 2: the business or disregarded entity name.
`asPayer[].profile.certification`	body	tax.Certification	—
`asPayer[].profile.certification.by`	body	string	—	By is who signed it: the IAM user legal recorded completing the signature.
`asPayer[].profile.certification.document`	body	string	—	Document is the /v1/legal document that carries the signature.
`asPayer[].profile.certification.signed`	body	integer (int64)	—	Signed is when legal reported the document signed, unix seconds.
`asPayer[].profile.certification.signer`	body	string	—	Signer is the IAM user the signature was opened for — the admin who asked.
`asPayer[].profile.certification.status`	body	string	—	Status is none, pending (a signature is open) or certified.
`asPayer[].profile.certification.version`	body	integer (int64)	—	Version is the profile version the signature covers.
`asPayer[].profile.classification`	body	string	—	Classification is line 3a.
`asPayer[].profile.consent`	body	tax.Consent	—
`asPayer[].profile.consent.at`	body	integer (int64)	—	At is when the consent was given or withdrawn, unix seconds.
`asPayer[].profile.consent.by`	body	string	—	By is the IAM user who gave or withdrew it.
`asPayer[].profile.consent.electronic`	body	boolean	—	Electronic is true while the consent stands.
`asPayer[].profile.disclosure`	body	string	—	Disclosure is the electronic-delivery disclosure the consent is given against.
`asPayer[].profile.exemptPayee`	body	string	—	ExemptPayee is line 4's exempt payee code, 1–13.
`asPayer[].profile.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.
`asPayer[].profile.fatca`	body	string	—	FATCA is line 4's FATCA exemption code, A–M.
`asPayer[].profile.foreignOwners`	body	boolean	—	ForeignOwners is line 3b: a flow-through entity with foreign partners, owners or beneficiaries.
`asPayer[].profile.foreignTin`	body	string	—	ForeignTIN is a W-8's foreign tax identifying number, masked.
`asPayer[].profile.form`	body	string	—	Form is w9, w8ben or w8bene.
`asPayer[].profile.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.
`asPayer[].profile.phone`	body	string	—	Phone is the number a 1099 this org files as PAYER prints for it.
`asPayer[].profile.tin`	body	string	—	TIN is Part I, masked to its last four digits.
`asPayer[].profile.tinType`	body	string	—	TINType is which Part I box: ssn (an SSN or ITIN) or ein.
`asPayer[].profile.updatedAt`	body	integer (int64)	—	UpdatedAt is when the profile last changed, unix seconds.
`asPayer[].profile.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.
`asPayer[].profile.version`	body	integer (int64)	—	Version counts the W-9's revisions; a certification covers exactly one.
`asPayer[].profile.w8`	body	tax.W8	—
`asPayer[].profile.w8.birth`	body	string	—	Birth is W-8BEN line 8, the individual's date of birth, YYYY-MM-DD.
`asPayer[].profile.w8.capacity`	body	string	—	Capacity is the capacity in which the signer signs for the beneficial owner — "Director", "Authorized officer".
`asPayer[].profile.w8.chapter3`	body	string	—	Chapter3 is W-8BEN-E line 4.
`asPayer[].profile.w8.chapter4`	body	string	—	Chapter4 is W-8BEN-E line 5, the FATCA status.
`asPayer[].profile.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.
`asPayer[].profile.w8.giin`	body	string	—	GIIN is W-8BEN-E line 9a, when the chapter 4 status carries one.
`asPayer[].profile.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.
`asPayer[].profile.w8.treaty`	body	tax.Treaty	—
`asPayer[].profile.w8.treaty.article`	body	string	—	Article is the treaty article and paragraph claimed, e.g. "12(2)".
`asPayer[].profile.w8.treaty.conditions`	body	string	—	Conditions is the explanation the form asks for: the conditions of the article the beneficial owner meets.
`asPayer[].profile.w8.treaty.country`	body	string	—	Country is the treaty country the beneficial owner is resident in.
`asPayer[].profile.w8.treaty.income`	body	string	—	Income is the type of income the claim covers: services, rents, royalties or other.
`asPayer[].profile.w8.treaty.lob`	body	string	—	LOB is W-8BEN-E line 14b: the treaty's limitation on benefits provision the entity meets.
`asPayer[].profile.w8.treaty.rateBps`	body	integer (int64)	—	RateBps is the claimed withholding rate in basis points: 0 is exempt, 1000 is 10%.
`asPayer[].requestedAt`	body	integer (int64)	—	RequestedAt is when the payer asked, unix seconds.
`asPayer[].role`	body	string	—	Role is the caller's side of it: payer or payee.
`asPayer[].status`	body	string	—	Status is requested, granted, declined or revoked.

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.getTaxW9();

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).get_tax_w9()

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

resp, _, err := client.TaxAPI.GetTaxW9(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::get_tax_w9(&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).getTaxW9();

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 https://api.hanzo.ai/v1/tax/w9 \
  -H "Authorization: Bearer $HANZO_API_KEY"

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