List filings
Lists the caller org's IRS return exports and where each stands, without their files.
GET /v1/tax/filings
| Address | https://api.hanzo.ai/v1/tax/filings |
| Method | GET |
| Operation | get_tax_filings |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Lists the caller org's IRS return exports and where each stands, without their files. Org admins only.
Request
GET /v1/tax/filings takes no parameters and no body — the credential is the whole request.
Response
| Status | Body | Meaning |
|---|---|---|
200 | tax.filingList | ok |
default | problem-details | refused |
200 body — 20 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
data | body | tax.Filing[] | — | Data are the filings, oldest first, without their files. |
data[].createdAt | body | integer (int64) | — | CreatedAt is when it was exported, unix seconds. |
data[].due | body | string | — | Due is when the return is due to the IRS. |
data[].forms | body | string[] | — | Forms are the form ids the filing carries. |
data[].id | body | string | — | ID is the filing's id, "iris_"-prefixed. |
data[].kind | body | string | — | Kind is 1099-NEC or 1099-MISC — one per filing, as IRIS takes them. |
data[].layout | body | string | — | Layout says what the files are. |
data[].missingTin | body | string[] | — | MissingTIN are forms filed with no recipient TIN. |
data[].parts | body | tax.Part[] | — | Parts are its files. |
data[].parts[].csv | body | string | — | CSV is the file itself. |
data[].parts[].digest | body | string | — | Digest is the SHA-256 of its bytes, hex, so a re-read proves it is the same file. |
data[].parts[].name | body | string | — | Name is the file name, e.g. "1099-NEC-2026-original-1.csv". |
data[].parts[].records | body | integer (int64) | — | Records is how many forms it holds, at most 250. |
data[].parts[].type | body | string | — | Type is original or correction: the portal takes them apart. |
data[].receiptId | body | string | — | ReceiptID is the Receipt ID IRIS returned, once the payer recorded one. |
data[].status | body | string | — | Status is exported, submitted, accepted, accepted_with_errors or rejected. |
data[].steps | body | string[] | — | Steps are what remains for the payer to do, in order. |
data[].tcc | body | string | — | TCC is the payer's IRIS Transmitter Control Code, once it recorded a submission. |
data[].updatedAt | body | integer (int64) | — | UpdatedAt is when its status last moved, unix seconds. |
data[].year | body | integer (int64) | — | Year is the tax year. |
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.getTaxFilings();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_filings()cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.TaxAPI.GetTaxFilings(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_filings(&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).getTaxFilings();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/filings \
-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.
How is this guide?