Create correct

POST /v1/tax/forms/{id}/correct

Tax → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/tax/forms/{id}/correct`
Method	`POST`
Operation	`post_tax_forms_by_id_correct`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Corrects a furnished (or owed) 1099 with a NEW form that supersedes it. Org admins only.

The furnished form is never changed: the correction is a second form, marked CORRECTED, carrying the original's account number and naming the form it supersedes, and it goes through review and furnishing like any other. State the corrected boxes, or omit them to derive the year again from the payments and the payee's current W-9. A form already superseded is corrected by correcting its successor. It files nothing with the IRS.

Request

7 fields, body application/json (required).

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the furnished form to correct, from the path.
`boxes`	body	tax.Amount[]	—	Boxes are the corrected amounts, by box.
`boxes[].box`	body	string	—	Box is the box number, e.g. "1a".
`boxes[].cents`	body	integer (int64)	—	Cents is the amount in cents.
`boxes[].label`	body	string	—	Label is the box's caption on the form.
`id`	body	string	—	ID is the furnished form to correct, from the path.
`reason`	body	string	—	Reason says what was wrong.

Response

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

201 body — 58 fields.

Field	In	Type	Always	Description
`account`	body	string	—	Account is the account number the form prints — the original form's id, which a correction keeps, so the IRS can tie the two.
`backup`	body	tax.Withholding	—
`backup.dueCents`	body	integer (int64)	—	DueCents is what 24% of the reported boxes comes to — what should have been withheld.
`backup.rate`	body	integer (int64)	—	Rate is the backup withholding rate, in percent: 24.
`backup.reason`	body	string	—	Reason says why, and which rule — or, when nothing is required, what the payer should still know.
`backup.required`	body	boolean	—	Required is true when the payer holds no TIN for the payee — the IRC §3406(a)(1)(A) trigger these forms can know.
`boxes`	body	tax.Amount[]	—	Boxes are the figures, box 4 (federal income tax withheld) included.
`boxes[].box`	body	string	—	Box is the box number, e.g. "1a".
`boxes[].cents`	body	integer (int64)	—	Cents is the amount in cents.
`boxes[].label`	body	string	—	Label is the box's caption on the form.
`certified`	body	boolean	—	Certified is whether the payee's W-9 was certified when the form was prepared.
`corrected`	body	boolean	—	Corrected is true for a form that corrects one already furnished.
`createdAt`	body	integer (int64)	—	CreatedAt is when the form was prepared, unix seconds.
`delivery`	body	string	—	Delivery is electronic (Copy B in the payee's inbox) or paper, once furnished.
`due`	body	tax.Deadline	—
`due.file`	body	string	—	File is the date the return is due to the IRS, electronically (IRIS).
`due.furnish`	body	string	—	Furnish is the date Copy B is due to the recipient.
`furnishedAt`	body	integer (int64)	—	FurnishedAt is when Copy B was delivered in the inbox, or marked owed on paper.
`id`	body	string	—	ID is the form's id, "f1099_"-prefixed.
`kind`	body	string	—	Kind is 1099-NEC or 1099-MISC.
`mailedAt`	body	integer (int64)	—	MailedAt is when the payer recorded mailing a paper Copy B.
`notes`	body	string[]	—	Notes are what still needs a person, in words.
`payer`	body	tax.Party	—
`payer.address`	body	tax.Address	—
`payer.address.city`	body	string	—	City is the city or town.
`payer.address.country`	body	string	—	Country is ISO 3166-1 alpha-2; "US" when absent.
`payer.address.line1`	body	string	—	Line1 is the number, street, and apartment or suite.
`payer.address.line2`	body	string	—	Line2 continues the street address, when there is more of it.
`payer.address.state`	body	string	—	State is the two-letter state or territory code.
`payer.address.zip`	body	string	—	ZIP is five or nine digits.
`payer.businessName`	body	string	—	BusinessName is W-9 line 2, when there is one.
`payer.name`	body	string	—	Name is W-9 line 1.
`payer.org`	body	string	—	Org is the Hanzo org.
`payer.phone`	body	string	—	Phone is the payer's telephone number; a recipient has none on the form.
`payer.tin`	body	string	—	TIN is masked here always.
`payer.tinType`	body	string	—	TINType is ssn or ein; empty when no TIN is held.
`payments`	body	string[]	—	Payments are the rail payment ids summed into the boxes.
`reason`	body	string	—	Reason is why a corrected form was made.
`recipient`	body	tax.Party	—
`recipient.address`	body	tax.Address	—
`recipient.address.city`	body	string	—	City is the city or town.
`recipient.address.country`	body	string	—	Country is ISO 3166-1 alpha-2; "US" when absent.
`recipient.address.line1`	body	string	—	Line1 is the number, street, and apartment or suite.
`recipient.address.line2`	body	string	—	Line2 continues the street address, when there is more of it.
`recipient.address.state`	body	string	—	State is the two-letter state or territory code.
`recipient.address.zip`	body	string	—	ZIP is five or nine digits.
`recipient.businessName`	body	string	—	BusinessName is W-9 line 2, when there is one.
`recipient.name`	body	string	—	Name is W-9 line 1.
`recipient.org`	body	string	—	Org is the Hanzo org.
`recipient.phone`	body	string	—	Phone is the payer's telephone number; a recipient has none on the form.
`recipient.tin`	body	string	—	TIN is masked here always.
`recipient.tinType`	body	string	—	TINType is ssn or ein; empty when no TIN is held.
`status`	body	string	—	Status is draft, reviewed, furnished, owed or void.
`supersededBy`	body	string	—	SupersededBy is the form that corrects this one, once there is one.
`supersedes`	body	string	—	Supersedes is the form this one corrects.
`updatedAt`	body	integer (int64)	—	UpdatedAt is when its status last moved, unix seconds.
`w9`	body	string	—	W9 is where the payer's W-9 request stood when the form was prepared.
`year`	body	integer (int64)	—	Year is the calendar year the payments were made.

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.postTaxFormsByIdCorrect({ id: 'id', boxes: [{"box":"<box>","cents":0,"label":"<label>"}], id: "<id>" });

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_forms_by_id_correct(id='id', boxes=[{"box":"<box>","cents":0,"label":"<label>"}], id="<id>")

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

resp, _, err := client.TaxAPI.PostTaxFormsByIdCorrect(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_forms_by_id_correct(&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).postTaxFormsByIdCorrect();

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/forms/<id>/correct \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "boxes": [
         {
           "box": "<box>",
           "cents": 0,
           "label": "<label>"
         }
       ],
       "id": "<id>"
     }'

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