# Create filings

URL: https://docs.hanzo.ai/docs/openapi/tax/post-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/filings`

> [Tax →](https://docs.hanzo.ai/docs/openapi/tax) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                        |
| ------------- | -------------------------------------- |
| **Address**   | `https://api.hanzo.ai/v1/tax/filings`  |
| **Method**    | `POST`                                 |
| **Operation** | `post_tax_filings`                     |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY` |

Exports the caller org's return for a tax year and form, as the files the IRIS
Taxpayer Portal takes, and records the export. Org admins of the payer only: the
files carry TINs in full, so a SuperAdmin acting inside the org is refused here
exactly as at the TIN read.

It carries every furnished (or owed) form of that year and kind not already in
an earlier export that IRIS did not reject — a rejected submission filed
nothing, so its forms go out again as originals. Originals are in one set of
files and corrections of forms already exported in another, at most 250 records
a file, each written to every rule Pub 5717 §3.5 sets and checked against them
before it is answered. The files carry full TINs: the export is on the audit
trail and the files are not stored, only rebuilt from the sealed forms when read
again.

It DOES NOT FILE WITH THE IRS. Submitting through IRIS needs the payer's own
Transmitter Control Code and a person at the portal; the answer lists those
steps, and POST /v1/tax/filings/{id}/receipt records what IRIS answered.

## Request

2 fields, body `application/json` (required).

| Field  | In   | Type            | Required | Description                    |
| ------ | ---- | --------------- | -------- | ------------------------------ |
| `kind` | body | string          | —        | Kind is 1099-NEC or 1099-MISC. |
| `year` | body | integer (int64) | —        | Year is the tax year.          |

## Response

| Status    | Body            | Meaning |
| --------- | --------------- | ------- |
| `201`     | tax.Filing      | created |
| `default` | problem-details | refused |

`201` body — 19 fields.

| Field             | In   | Type            | Always | Description                                                                       |
| ----------------- | ---- | --------------- | ------ | --------------------------------------------------------------------------------- |
| `createdAt`       | body | integer (int64) | —      | CreatedAt is when it was exported, unix seconds.                                  |
| `due`             | body | string          | —      | Due is when the return is due to the IRS.                                         |
| `forms`           | body | string\[]       | —      | Forms are the form ids the filing carries.                                        |
| `id`              | body | string          | —      | ID is the filing's id, "iris\_"-prefixed.                                         |
| `kind`            | body | string          | —      | Kind is 1099-NEC or 1099-MISC — one per filing, as IRIS takes them.               |
| `layout`          | body | string          | —      | Layout says what the files are.                                                   |
| `missingTin`      | body | string\[]       | —      | MissingTIN are forms filed with no recipient TIN.                                 |
| `parts`           | body | tax.Part\[]     | —      | Parts are its files.                                                              |
| `parts[].csv`     | body | string          | —      | CSV is the file itself.                                                           |
| `parts[].digest`  | body | string          | —      | Digest is the SHA-256 of its bytes, hex, so a re-read proves it is the same file. |
| `parts[].name`    | body | string          | —      | Name is the file name, e.g. "1099-NEC-2026-original-1.csv".                       |
| `parts[].records` | body | integer (int64) | —      | Records is how many forms it holds, at most 250.                                  |
| `parts[].type`    | body | string          | —      | Type is original or correction: the portal takes them apart.                      |
| `receiptId`       | body | string          | —      | ReceiptID is the Receipt ID IRIS returned, once the payer recorded one.           |
| `status`          | body | string          | —      | Status is exported, submitted, accepted, accepted\_with\_errors or rejected.      |
| `steps`           | body | string\[]       | —      | Steps are what remains for the payer to do, in order.                             |
| `tcc`             | body | string          | —      | TCC is the payer's IRIS Transmitter Control Code, once it recorded a submission.  |
| `updatedAt`       | body | integer (int64) | —      | UpdatedAt is when its status last moved, unix seconds.                            |
| `year`            | body | integer (int64) | —      | Year is the tax year.                                                             |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

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

**SDK**

**.ts**

```ts
import { Configuration, TaxApi } from 'hanzoai';

const api = new TaxApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postTaxFilings({ kind: "<kind>", year: 0 });
```

**.py**

```python
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_filings(kind="<kind>", year=0)
```

**.go**

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

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

**.rs**

```rust
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_filings(&cfg, Default::default()).await?;
```

**.java**

```java
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).postTaxFilings();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/tax/filings \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "kind": "<kind>",
       "year": 0
     }'
```

**MCP**

MCP reaches **tax** through the `tax` tool, which names its 26 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_tax_filings"
         }
       }
     }'
```

---

[Tax API](https://docs.hanzo.ai/docs/openapi/tax) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)