Tax
How companies formed on Hanzo exchange W-9s, W-8s and 1099s with each other, from the payments that moved between them on Hanzo's rails.
How companies formed on Hanzo exchange W-9s, W-8s and 1099s with each other, from the payments that moved between them on Hanzo's rails.
| Base URL | https://api.hanzo.ai |
| Operations | 28 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Specification
Specification pending — no HIP in hanzoai/hips declares capability: tax yet. What this capability serves is below, from the API document; what it is — the store it owns, how it meters, what it publishes — is written as a HIP under HIP-0139.
Four surfaces
| Surface | Reaches this capability as | Coverage |
|---|---|---|
| REST | tax at its own prefix | 28 operations |
| CLI | — | no command reaches it yet — use HTTP or an SDK |
| SDK | — | no published client declares one yet — regenerating the clients is what adds them |
| MCP | — | no tool names it yet — use HTTP or an SDK |
Quickstart
export HANZO_API_KEY=sk-... # console.hanzo.ai → API keysThen the first call — a read that needs nothing but the key. GET /v1/tax/w9, operation get_tax_w9:
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.
Answers 200 with object — ok.
Endpoints
| Endpoint | What it does |
|---|---|
POST /v1/tax/filings/{id}/receipt | Records what IRIS answered for an exported return — the Receipt ID on submission, then the acknowledgment. |
GET /v1/tax/filings/{id} | Reads one IRS return export WITH its files, rebuilt from the sealed forms and proven identical to what was exported. |
GET /v1/tax/filings | Lists the caller org's IRS return exports and where each stands, without their files. |
POST /v1/tax/filings | Exports the caller org's return for a tax year and form, as the files the IRIS Taxpayer Portal takes, and records the export. |
POST /v1/tax/forms/{id}/correct | Corrects a furnished (or owed) 1099 with a NEW form that supersedes it. |
POST /v1/tax/forms/{id}/furnish | Furnishes Copy B of a reviewed 1099 to its payee. |
POST /v1/tax/forms/{id}/mailed | Records that the payer mailed a paper Copy B it owed. |
GET /v1/tax/forms/{id}/pdf | Download a 1099 the org prepared, as a PDF |
POST /v1/tax/forms/{id}/review | Marks a draft 1099 reviewed — a person has checked it. |
POST /v1/tax/forms/{id}/void | Voids a draft or reviewed 1099, which is then never furnished or filed. |
GET /v1/tax/forms/{id} | Reads one 1099 the caller org prepared as payer, every box and both parties, TINs masked. |
GET /v1/tax/forms | Lists the 1099s the caller org prepared as payer, oldest first, voided and superseded ones included — a return that was furnished stays on the record. |
POST /v1/tax/forms | Prepares the caller org's 1099 drafts for a tax year, as the PAYER: one 1099-NEC and/or 1099-MISC per payee whose reportable payments on Hanzo's rails reach the year's threshold, from the same derivation GET /v1/tax/payments answers. |
GET /v1/tax/inbox/{id}/pdf | Download a Copy B furnished to the org, as a PDF |
GET /v1/tax/inbox/{id} | Reads one Copy B furnished to the caller org. |
GET /v1/tax/inbox | Lists the Copy B statements furnished to the caller org — every 1099 a payer on Hanzo delivered to it electronically, corrected ones beside the ones they supersede. |
GET /v1/tax/payments | Returns the caller org's tax year as a PAYER: every payment it made to another org in that calendar year, on any rail, as the event plane records it, each classified — reportable or not, in which 1099 box, and the rule that decided it, with its source — and each payee's totals tested against the year's threshold. |
POST /v1/tax/profile/certify | Signs the caller org's certification — Form W-9 Part II, Form W-8BEN Part III or Form W-8BEN-E Part XXX — through /v1/legal's e-signature. |
GET /v1/tax/profile | Returns the caller org's own tax profile — every line of its Form W-9, W-8BEN or W-8BEN-E, every number masked to its last four characters, where the certification stands, whether a W-8 is valid and when it expires, and whether the org consents to receive its 1099s electronically. |
PUT /v1/tax/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. |
POST /v1/tax/w9/{id}/decline | Declines a request for this org's W-9. |
POST /v1/tax/w9/{id}/grant | Grants the payer that asked a live read of this org's W-9 — every line, the TIN masked, and the full TIN to that payer's org admins alone, each read audited. |
POST /v1/tax/w9/{id}/match | Records the result of IRS TIN Matching for a payee, as the payer. |
POST /v1/tax/w9/{id}/revoke | Revokes a W-9 this org granted. |
GET /v1/tax/w9/{id}/tin | Reads a payee's TIN in full — and, for a payee on a W-8, its foreign TIN, which the payer's Form 1042-S carries. |
GET /v1/tax/w9/{id} | Reads one W-9 relationship from the caller's side. |
GET /v1/tax/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. |
POST /v1/tax/w9 | Asks another org for its W-9, as the org that pays it. |
How is this guide?