Create match

POST /v1/tax/w9/{id}/match

Tax → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/tax/w9/{id}/match`
Method	`POST`
Operation	`post_tax_w9_by_id_match`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Records the result of IRS TIN Matching for a payee, as the payer. Org admins of the payer only, on a live grant.

It does not run TIN Matching. That is an IRS e-Services program a payer enrolls in and runs itself, on the name and TIN it holds; this records what the IRS answered so it sits beside the W-9 and on the audit trail. Nothing here ever records a match the payer did not report.

Request

3 fields, body application/json (required).

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the relationship, from the path.
`id`	body	string	—	ID is the relationship, from the path.
`result`	body	string	—	Result is what IRS TIN Matching answered for this payee's name and TIN: matched or mismatched.

Response

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

200 body — 62 fields.

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

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).post_tax_w9_by_id_match(id='id', id="<id>", result="<result>")

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

resp, _, err := client.TaxAPI.PostTaxW9ByIdMatch(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::post_tax_w9_by_id_match(&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).postTaxW9ByIdMatch();

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 POST https://api.hanzo.ai/v1/tax/w9/<id>/match \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "id": "<id>",
       "result": "<result>"
     }'

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