{"openapi":"3.1.0","info":{"title":"IrisTaxFiling API","version":"0.1.0","description":"Validate, prepare, submit, track and correct US information returns. Use a test key (if_test_...) for the built-in IRS simulator. Live filing is not available. XML output is provisional until the IRS schema package is loaded."},"servers":[{"url":"https://api.iristaxfiling.com","description":"Hosted (test mode only: IRS simulator, no live filing)"},{"url":"http://127.0.0.1:8787","description":"Local (irisfile dev)"}],"security":[{"bearer":[]}],"paths":{"/v1/filings":{"post":{"summary":"Create a filing (add ?mode=validate for a dry run that stores nothing)","parameters":[{"name":"mode","in":"query","schema":{"type":"string","enum":["validate"]}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Safe retries: same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingInput"}}}},"responses":{"200":{"description":"Dry-run result"},"201":{"description":"Filing created (status ready or blocked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filing"}}}},"409":{"description":"Idempotency conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/filings/{id}":{"get":{"summary":"Get a filing (applies a pending IRS acknowledgement)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filing"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/filings/{id}/submit":{"post":{"summary":"Submit a ready filing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filing"}}}},"409":{"description":"Wrong state","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"501":{"description":"Live mode unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Transmission failed, retryable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/filings/{id}/acknowledgements":{"get":{"summary":"Raw IRS acknowledgements","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List"},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/filings/{id}/corrections":{"post":{"summary":"Create a correction or replacement of a finished filing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["correction","replacement"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingInput"}}}},"responses":{"201":{"description":"Correction created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filing"}}}}}}},"/v1/forms":{"get":{"summary":"All IRIS forms with tax-year availability and IrisTaxFiling support level (filter: ?family=)","parameters":[{"name":"family","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List"}}}},"/v1/forms/{id}":{"get":{"summary":"One form with its IRS template columns and rules","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Form"},"404":{"description":"Unknown form","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/forms/{id}/template":{"get":{"summary":"Download a CSV template (header plus an example row) for a form","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/csv"},"404":{"description":"Unknown form","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/forms/{id}/validate":{"post":{"summary":"Readiness check for a CSV (text/csv, IRS template layout) or JSON rows. Stores nothing.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Readiness report: status, counts, grouped problems with row numbers and fixes"},"404":{"description":"Unknown form","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/imports/fire":{"post":{"summary":"Convert a FIRE file (IRS Pub 1220 layout, text body) into filings for 1099-NEC, -MISC, -INT and -DIV. Stores nothing unless ?create=true.","parameters":[{"name":"create","in":"query","schema":{"type":"string","enum":["true"]},"description":"Create the filings. Re-sending the same file does not create duplicates."}],"responses":{"200":{"description":"Import result: summary, issues (skipped records, count and control-total mismatches) and each filing with its readiness"},"413":{"description":"Too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Empty body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/tin/check":{"post":{"summary":"Check a TIN format (never echoes the full TIN)","responses":{"200":{"description":"Result"},"422":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks":{"get":{"summary":"List webhook endpoints","responses":{"200":{"description":"List"}}},"post":{"summary":"Register a webhook endpoint (the signing secret is returned once)","responses":{"201":{"description":"Created"},"422":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/deliveries":{"get":{"summary":"Recent webhook deliveries and retry state","responses":{"200":{"description":"List"}}}},"/v1/audit":{"get":{"summary":"Audit log of actions on this account (filing created, submitted)","responses":{"200":{"description":"List"}}}},"/v1/usage":{"get":{"summary":"Metered filings for a period (YYYY-MM)","parameters":[{"name":"period","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Usage"},"422":{"description":"Invalid period","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"if_test_... or if_live_..."}},"schemas":{"Problem":{"type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"}}}}}},"FilingInput":{"type":"object","required":["form","tax_year","payer","recipients"],"additionalProperties":false,"properties":{"form":{"type":"string","enum":["1099-NEC","1099-DIV","1099-INT","1099-MISC"]},"tax_year":{"type":"integer"},"payer":{"type":"object"},"recipients":{"type":"array","items":{"type":"object"}},"correction":{"type":"object"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"Filing":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"filing"},"status":{"type":"string","enum":["created","blocked","ready","submitted","accepted","accepted_with_errors","partially_accepted","rejected","failed","corrected"]},"mode":{"type":"string","enum":["test","live"]},"form":{"type":"string"},"tax_year":{"type":"integer"},"recipient_count":{"type":"integer"},"summary":{"type":"object","properties":{"blockers":{"type":"integer"},"warnings":{"type":"integer"}}},"issues":{"type":"array","items":{"type":"object"}},"receipt_id":{"type":"string"},"correction_of":{"type":"string"}}}}},"x-webhook-events":["filing.created","filing.validated","filing.ready","filing.submitted","filing.accepted","filing.rejected","filing.failed","correction.required","filing.corrected"]}