{"openapi":"3.1.0","info":{"title":"IRISfile filing API","version":"v1","summary":"Validate, convert and file 1099s with the IRS through IRIS A2A.","description":"Private beta. Sandbox keys (`irf_test_`) file with the IRS test system and never file a live return. Errors share one shape: `{ \"error\": { \"code\", \"message\", \"requestId\"? } }`; branch on `code`.","contact":{"email":"support@irisfile.co","url":"https://irisfile.co/docs/api"}},"servers":[{"url":"https://irisfile.co"}],"security":[{"bearerKey":[]},{"apiKeyHeader":[]}],"paths":{"/api/v1/validate":{"post":{"operationId":"validate","summary":"Check a file without storing it","description":"Runs the dashboard's parse and validation on a file or on records. Stores nothing. Send multipart/form-data with a `file` field (FIRE, CSV, Excel or IRIS XML, read by its extension), or application/json `{ \"records\": [...] }`. An account without a license for the file's tax year uses a preview file and gets only the first records checked.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}},"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/Form1099Record"},"minItems":1,"maxItems":100000}},"required":["records"]}}}},"responses":{"200":{"description":"The validation report.","content":{"application/json":{"schema":{"type":"object","properties":{"validation":{"$ref":"#/components/schemas/Validation"}},"required":["validation"]}}}},"400":{"description":"The body is not what this operation reads.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"402":{"description":"The account has used its preview files. Buy a license.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["preview_limit_reached"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"413":{"description":"The request body is over 4.5 MB.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["payload_too_large"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"422":{"description":"The file could not be read at all.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["parse_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/uploads":{"post":{"operationId":"createUpload","summary":"Reserve a direct upload for a large file","description":"For files over 4.5 MB, up to 50 MB. PUT the bytes to `uploadUrl` with `headers` and exactly `size` bytes within 10 minutes, then call POST /api/v1/submissions with `{ uploadToken, filename }`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","description":"Its extension picks the parser: .fire, .txt, .csv, .xlsx or .xml."},"size":{"type":"integer","description":"Exact size in bytes."},"contentType":{"type":"string","description":"Defaults to application/octet-stream."}},"required":["filename","size"]}}}},"responses":{"201":{"description":"The reservation.","content":{"application/json":{"schema":{"type":"object","properties":{"upload":{"type":"object","properties":{"uploadToken":{"type":"string","format":"uuid"},"uploadUrl":{"type":"string","description":"Presigned storage URL.","format":"uri"},"method":{"type":"string","enum":["PUT"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expiresIn":{"type":"integer","description":"Seconds the URL stays valid."}},"required":["uploadToken","uploadUrl","method","headers","expiresIn"]}},"required":["upload"]}}}},"400":{"description":"The body is not what this operation reads.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"402":{"description":"The account has used its preview files. Buy a license.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["preview_limit_reached"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"413":{"description":"The file is over 50 MB, or the account has too many bytes waiting to upload.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["payload_too_large"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/submissions":{"post":{"operationId":"createSubmission","summary":"Create a submission and convert it","description":"Multipart `file` (up to 4.5 MB) usually converts in this request and answers 201. It answers 202 when the file is queued for the worker: a file with more than 10 payer EINs, or a file converted with a saved column layout. An optional `uploadToken` UUID field lets a retry of a queued multi-payer upload find the same submission; it has no effect on a file converted in the request. JSON `{ uploadToken, filename }` after POST /api/v1/uploads queues the stored file for the worker and is idempotent on the token. Conversion and validation are free. A file with several payer EINs splits into one child submission per payer.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"uploadToken":{"type":"string","format":"uuid"}},"required":["file"]}},"application/json":{"schema":{"type":"object","properties":{"uploadToken":{"type":"string","description":"From POST /api/v1/uploads.","format":"uuid"},"filename":{"type":"string"}},"required":["uploadToken","filename"]}}}},"responses":{"200":{"description":"A retried upload that already has a submission.","content":{"application/json":{"schema":{"type":"object","properties":{"submission":{"$ref":"#/components/schemas/Submission"}},"required":["submission"]}}}},"201":{"description":"Converted in this request, or parked for column mapping in the dashboard.","content":{"application/json":{"schema":{"type":"object","properties":{"submission":{"$ref":"#/components/schemas/Submission"}},"required":["submission"]}}}},"202":{"description":"Queued for the worker. Poll GET /api/v1/submissions/{id} or wait for `submission.converted`.","content":{"application/json":{"schema":{"type":"object","properties":{"submission":{"$ref":"#/components/schemas/Submission"}},"required":["submission"]}}}},"400":{"description":"The body is not what this operation reads.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"402":{"description":"The account has used its preview files. Buy a license.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["preview_limit_reached"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"404":{"description":"No such submission for this key. Another account's id, and a row in the other environment, read as missing.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"409":{"description":"The PUT to `uploadUrl` did not complete.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["upload_not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"413":{"description":"The body is over 4.5 MB, or the uploaded file is over 50 MB.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["payload_too_large"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"422":{"description":"The file could not be read, or its columns need mapping and mapping is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["mapping_unavailable","parse_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"Too many requests, active upload jobs, or files waiting for column mapping.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/submissions/{id}":{"get":{"operationId":"getSubmission","summary":"Get a submission","description":"Status, stage, counts, the quote for unpaid forms, the credit balance and each transmission.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The submission.","content":{"application/json":{"schema":{"type":"object","properties":{"submission":{"$ref":"#/components/schemas/Submission"}},"required":["submission"]}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"404":{"description":"No such submission for this key. Another account's id, and a row in the other environment, read as missing.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/submissions/{id}/diagnostics":{"get":{"operationId":"listDiagnostics","summary":"List a submission's errors, warnings and notices","description":"Keyset paged in record order. File-level messages come first.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"severity","in":"query","schema":{"type":"string","enum":["error","warning","info"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200},"description":"Clamped to 1-1000."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The previous page's `nextCursor`."}],"responses":{"200":{"description":"One page.","content":{"application/json":{"schema":{"type":"object","properties":{"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/StoredDiagnostic"}},"nextCursor":{"type":["string","null"]}},"required":["diagnostics","nextCursor"]}}}},"400":{"description":"Unknown severity or a cursor that is not valid.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"404":{"description":"No such submission for this key. Another account's id, and a row in the other environment, read as missing.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/submissions/{id}/file":{"post":{"operationId":"fileSubmission","summary":"File a submission with the IRS","description":"Files under IRISfile's TCC. A sandbox key files sandbox rows with the IRS test system (TestCd T). A production row needs application/json `{ \"reviewed\": true }`. The file's tax-year license and form credits for every unpaid form are checked before any UTID exists; a form already paid costs nothing. Sandbox rows on irisfile.co need no license and are never billed. Retrying is safe: a transmission with a UTID is never resubmitted, only looked up.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reviewed":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"Every transmission has an IRS receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"`submitted`, or the stored status when every transmission already had a receipt."},"transmissions":{"type":"array","items":{"$ref":"#/components/schemas/FiledTransmission"}},"billing":{"$ref":"#/components/schemas/Billing"}},"required":["status","transmissions","billing"]}}}},"400":{"description":"A body that is not a JSON object, or a production row without `{ \"reviewed\": true }`.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","review_required"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"402":{"description":"`license_required`: buy the tax year's license in the dashboard. `payment_required`: buy form credits. Nothing was debited.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["license_required","payment_required"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}},"lockedUnits":{"type":"integer","description":"With `payment_required`: unpaid forms."},"quoteCents":{"type":"integer","description":"With `payment_required`: what they cost now, in cents."},"balanceCents":{"type":"integer","description":"With `payment_required`: the account's credit balance, in cents."},"years":{"type":"array","items":{"type":"object"},"description":"With `payment_required`: the quote by tax year."},"taxYear":{"type":"integer","description":"With `license_required`: the first tax year without a license."},"seatPriceCents":{"type":"integer","description":"With `license_required`: the price of one license seat, in cents."}}}}}},"404":{"description":"No such submission for this key. Another account's id, and a row in the other environment, read as missing.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"409":{"description":"The submission cannot file now. `filing_incomplete` carries `transmissions`, `unreceiptedSequences` and `billing`: retry later and nothing is resubmitted. `correction_predecessor_claimed`: another submission already corrects one of these returns. Nothing was sent. `prevUniqueRecordIds` names them. `correction_claim_released`: nothing was sent to the IRS for this transmission. The hold on the returns it corrects was released while it was filing. Retry the request to send it. Transmissions the IRS already has are not sent twice.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["checkout_pending","correction_claim_released","correction_predecessor_claimed","credits_frozen","filing_in_progress","filing_incomplete","not_fileable","not_ready","preview_truncated","regenerate_required","sandbox_output_unavailable","submission_deleting"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}},"status":{"type":"string","description":"With `not_fileable` and `filing_incomplete`."},"prevUniqueRecordIds":{"type":"array","items":{"type":"string"}},"transmissions":{"type":"array","items":{"$ref":"#/components/schemas/FiledTransmission"}},"unreceiptedSequences":{"type":"array","items":{"type":"integer"}},"billing":{"$ref":"#/components/schemas/Billing"}}}}}},"413":{"description":"The request body is over 4.5 MB.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["payload_too_large"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"Filing failed after the credit check. The body carries `billing`.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}},"billing":{"$ref":"#/components/schemas/Billing"}}}}}},"502":{"description":"The IRS refused or failed the call. The body carries `status`, `transmissions` and `billing`.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["irs_filing_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}},"status":{"type":"string"},"transmissions":{"type":"array","items":{"$ref":"#/components/schemas/FiledTransmission"}},"billing":{"$ref":"#/components/schemas/Billing"}}}}}},"503":{"description":"Filing is off on this deployment, its configuration is invalid, or billing is busy.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","filing_disabled","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","retry_later","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/submissions/{id}/outputs/{kind}":{"get":{"operationId":"getOutput","summary":"Download an output","description":"Answers 302 to a storage link that expires in 5 minutes; the JSON body repeats it. `xml` and `copy-b` need the tax-year license and debit nothing. `portal-csv` also debits form credits for unpaid forms. A sandbox row on irisfile.co serves only `xml`. A client that follows redirects loses the billing headers: read them with redirects off, or read the balance from GET /api/v1/submissions/{id}.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["xml","portal-csv","copy-b"]}},{"name":"transmission","in":"query","schema":{"type":"integer","minimum":1,"maximum":999999},"description":"`xml` only: the transmission sequence. Required when the file has several transmissions."}],"responses":{"302":{"description":"Redirect to the presigned link.","headers":{"Location":{"description":"The presigned link.","schema":{"type":"string","format":"uri"}},"IRISfile-Debited-Cents":{"description":"Credits this request spent.","schema":{"type":"integer"}},"IRISfile-Balance-Cents":{"description":"Credit balance after this request.","schema":{"type":"integer"}},"IRISfile-Excluded-Records":{"description":"Records left out of this output, when known.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"filename":{"type":"string"},"contentType":{"type":"string"},"excludedRecords":{"type":["integer","null"]},"billing":{"$ref":"#/components/schemas/Billing"}},"required":["url","expiresAt","filename","contentType","excludedRecords","billing"]}}}},"400":{"description":"`transmission` on a kind other than `xml`, or not a positive sequence.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"402":{"description":"`license_required`: buy the tax year's license in the dashboard. `payment_required`: buy form credits. Nothing was debited.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["license_required","payment_required"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}},"lockedUnits":{"type":"integer","description":"With `payment_required`: unpaid forms."},"quoteCents":{"type":"integer","description":"With `payment_required`: what they cost now, in cents."},"balanceCents":{"type":"integer","description":"With `payment_required`: the account's credit balance, in cents."},"years":{"type":"array","items":{"type":"object"},"description":"With `payment_required`: the quote by tax year."},"taxYear":{"type":"integer","description":"With `license_required`: the first tax year without a license."},"seatPriceCents":{"type":"integer","description":"With `license_required`: the price of one license seat, in cents."}}}}}},"404":{"description":"No such submission, transmission or output kind for this key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"409":{"description":"The output cannot be served now. `submission_split` lists `children`; `transmission_required` lists `transmissions`; `output_unavailable` carries `status` and `counts`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["checkout_pending","credits_frozen","not_ready","output_unavailable","preview_truncated","regenerate_required","sandbox_output_unavailable","submission_split","transmission_required"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}},"children":{"type":"array","items":{"type":"string","format":"uuid"}},"transmissions":{"type":"array","items":{"type":"object"}},"output":{"type":"string"},"status":{"type":"string"},"counts":{"type":"object"},"billing":{"$ref":"#/components/schemas/Billing"}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"Storage or billing is unavailable. Retry later.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","retry_later","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/webhook-endpoints":{"get":{"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","description":"Endpoints in the key's environment. A sandbox key sees sandbox endpoints only.","responses":{"200":{"description":"Newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"required":["endpoints"]}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}},"post":{"operationId":"createWebhookEndpoint","summary":"Register a webhook endpoint","description":"The URL must be https on port 443 with a public host name that resolves to public addresses only, or a public IP address. The response carries the signing secret once. An account holds up to 5 endpoints per environment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2048},"description":{"type":["string","null"],"maxLength":100}},"required":["url"]}}}},"responses":{"201":{"description":"Registered.","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string","description":"`whsec_...`. Shown once."}},"required":["endpoint","secret"]}}}},"400":{"description":"The body, the URL or the description failed a check.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"409":{"description":"The environment already has its maximum endpoints.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["webhook_endpoint_limit"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"413":{"description":"The request body is over 4.5 MB.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["payload_too_large"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/webhook-endpoints/{id}":{"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","description":"Cancels its pending deliveries. A delivery that has already started may still arrive.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"404":{"description":"No such endpoint for this key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/webhook-endpoints/{id}/test":{"post":{"operationId":"testWebhookEndpoint","summary":"Send a test event","description":"Queues a `webhook.test` event for this endpoint only, signed and retried like any other.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"]}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"404":{"description":"No such endpoint for this key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}},"/api/v1/webhook-endpoints/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List recent deliveries","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}},"required":["deliveries"]}}}},"400":{"description":"`limit` is not a whole number in range.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"401":{"description":"The key is missing, malformed, revoked or unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"404":{"description":"No such endpoint for this key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"429":{"description":"More than 60 requests in a minute with this key, or an upload limit for the account.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent only with a code that asks you to retry, such as `rate_limited`, `not_ready`, `filing_in_progress` or `retry_later`.","required":false,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"500":{"description":"An operational failure. Some work may have completed before the failure. A retry of JSON upload completion, or of a queued multi-payer multipart upload, with the same `uploadToken` finds its submission. Any other upload retried after a 500 may create a second submission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}},"503":{"description":"A dependency or the deployment configuration is unavailable. Retry later.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["already_filing","config_invalid","db_read_failed","db_write_failed","email_failed","irs_filing_failed","parse_failed","parse_memory","parse_timeout","pdf_generation_failed","request_aborted","storage_failed","stripe_failed","unknown","xml_generation_failed"]},"message":{"type":"string","description":"A sentence a person can read. Never parse it; branch on `code`."},"requestId":{"type":"string","description":"Support ID for an operational failure. Quote it when you contact support."}}}}}}}}}}}},"webhooks":{"submission.converted":{"post":{"operationId":"onSubmissionConverted","summary":"A conversion finished","description":"Sent as a signed POST with headers `IRISfile-Signature`, `IRISfile-Event-Id` and `IRISfile-Event-Type: submission.converted`. Answer 2xx within 10 seconds. Any other answer, a redirect included, is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 24 h; the delivery fails after 7 attempts.","parameters":[{"name":"IRISfile-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` of `${t}.${raw body}`, keyed with the endpoint secret. Reject a `t` more than 300 seconds from your clock."},{"name":"IRISfile-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"IRISfile-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["submission.converted"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string","enum":["submission.converted"]},"data":{"$ref":"#/components/schemas/SubmissionConvertedData"}},"required":["type","data"]}]}}}},"security":[],"responses":{"2XX":{"description":"Received. Any other status is retried."}}}},"transmission.receipted":{"post":{"operationId":"onTransmissionReceipted","summary":"The IRS gave a transmission its receipt ID","description":"Sent as a signed POST with headers `IRISfile-Signature`, `IRISfile-Event-Id` and `IRISfile-Event-Type: transmission.receipted`. Answer 2xx within 10 seconds. Any other answer, a redirect included, is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 24 h; the delivery fails after 7 attempts.","parameters":[{"name":"IRISfile-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` of `${t}.${raw body}`, keyed with the endpoint secret. Reject a `t` more than 300 seconds from your clock."},{"name":"IRISfile-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"IRISfile-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["transmission.receipted"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string","enum":["transmission.receipted"]},"data":{"$ref":"#/components/schemas/TransmissionEventData"}},"required":["type","data"]}]}}}},"security":[],"responses":{"2XX":{"description":"Received. Any other status is retried."}}}},"transmission.acknowledged":{"post":{"operationId":"onTransmissionAcknowledged","summary":"The IRS acknowledgement arrived (A, E, P or R)","description":"Sent as a signed POST with headers `IRISfile-Signature`, `IRISfile-Event-Id` and `IRISfile-Event-Type: transmission.acknowledged`. Answer 2xx within 10 seconds. Any other answer, a redirect included, is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 24 h; the delivery fails after 7 attempts.","parameters":[{"name":"IRISfile-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` of `${t}.${raw body}`, keyed with the endpoint secret. Reject a `t` more than 300 seconds from your clock."},{"name":"IRISfile-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"IRISfile-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["transmission.acknowledged"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string","enum":["transmission.acknowledged"]},"data":{"$ref":"#/components/schemas/TransmissionEventData"}},"required":["type","data"]}]}}}},"security":[],"responses":{"2XX":{"description":"Received. Any other status is retried."}}}},"transmission.failed":{"post":{"operationId":"onTransmissionFailed","summary":"The IRS refused the POST, or 72 hours passed with no acknowledgement","description":"Sent as a signed POST with headers `IRISfile-Signature`, `IRISfile-Event-Id` and `IRISfile-Event-Type: transmission.failed`. Answer 2xx within 10 seconds. Any other answer, a redirect included, is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 24 h; the delivery fails after 7 attempts.","parameters":[{"name":"IRISfile-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` of `${t}.${raw body}`, keyed with the endpoint secret. Reject a `t` more than 300 seconds from your clock."},{"name":"IRISfile-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"IRISfile-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["transmission.failed"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string","enum":["transmission.failed"]},"data":{"$ref":"#/components/schemas/TransmissionEventData"}},"required":["type","data"]}]}}}},"security":[],"responses":{"2XX":{"description":"Received. Any other status is retried."}}}},"webhook.test":{"post":{"operationId":"onWebhookTest","summary":"A test event you asked for","description":"Sent as a signed POST with headers `IRISfile-Signature`, `IRISfile-Event-Id` and `IRISfile-Event-Type: webhook.test`. Answer 2xx within 10 seconds. Any other answer, a redirect included, is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 24 h; the delivery fails after 7 attempts.","parameters":[{"name":"IRISfile-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256>` of `${t}.${raw body}`, keyed with the endpoint secret. Reject a `t` more than 300 seconds from your clock."},{"name":"IRISfile-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"IRISfile-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["webhook.test"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string","enum":["webhook.test"]},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["type","data"]}]}}}},"security":[],"responses":{"2XX":{"description":"Received. Any other status is retried."}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"An IRISfile API key: `irf_test_...` (sandbox) or `irf_live_...`."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Diagnostic":{"type":"object","properties":{"recordIndex":{"type":["integer","null"],"description":"0-based record index; null for a file-level message."},"sourceRow":{"type":["integer","null"],"description":"Row or line in the source file, when known."},"field":{"type":["string","null"],"description":"The record field, such as `payee.state`."},"severity":{"type":"string","enum":["error","warning","info"]},"code":{"type":["string","null"],"description":"A stable code for the check, when the check has one."},"message":{"type":"string","description":"What is wrong. TINs are redacted."}},"required":["recordIndex","sourceRow","field","severity","code","message"]},"StoredDiagnostic":{"allOf":[{"$ref":"#/components/schemas/Diagnostic"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}]},"Transmission":{"type":"object","properties":{"sequence":{"type":"integer","description":"1-based position in the submission. Pass it as `?transmission=` to download one XML."},"taxYear":{"type":"integer"},"records":{"type":"integer"},"status":{"type":"string","enum":["not_filed","awaiting_receipt","receipted","accepted","accepted_with_errors","partially_accepted","rejected"]},"utid":{"type":["string","null"],"description":"Unique Transmission ID, set before the IRS call."},"receiptId":{"type":["string","null"],"description":"IRS receipt ID."},"submittedAt":{"type":["string","null"],"description":"Timestamp with time zone, as Postgres prints it (for example `2026-10-21 14:03:22.5+00`)."},"ackCode":{"type":["string","null"],"enum":["A","E","P","R",null],"description":"IRS acknowledgement code."},"ackAt":{"type":["string","null"],"description":"Timestamp with time zone, as Postgres prints it (for example `2026-10-21 14:03:22.5+00`)."}},"required":["sequence","taxYear","records","status","utid","receiptId","submittedAt","ackCode","ackAt"]},"FiledTransmission":{"description":"A transmission with this request's outcome. When the stored rows cannot be reloaded, only `sequence`, `utid`, `receiptId` and `state` are present.","allOf":[{"type":"object","properties":{"sequence":{"type":"integer"},"taxYear":{"type":"integer"},"records":{"type":"integer"},"status":{"type":"string"},"utid":{"type":["string","null"]},"receiptId":{"type":["string","null"]},"submittedAt":{"type":["string","null"]},"ackCode":{"type":["string","null"]},"ackAt":{"type":["string","null"]}},"required":["sequence","utid","receiptId"]},{"type":"object","properties":{"state":{"type":"string","enum":["submitted","already_submitted","awaiting_irs","failed"]}},"required":["state"]}]},"Billing":{"type":"object","properties":{"debitedCents":{"type":"integer","description":"Credits this request spent, in cents."},"balanceCents":{"type":"integer","description":"Credit balance after this request, in cents."}},"required":["debitedCents","balanceCents"]},"Submission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["uploaded","needs_mapping","parsed","split","validated","xml_generated","submitted","accepted","accepted_with_errors","partially_accepted","rejected","needs_correction","ack_timeout","failed"]},"stage":{"type":"string","enum":["processing","needs_fixing","ready_to_unlock","ready_to_file","with_irs","accepted","split"],"description":"`ready_to_unlock` means forms in the file are not paid for yet."},"children":{"type":"array","items":{"type":"string","format":"uuid"},"description":"For a split file: one submission per payer."},"counts":{"type":"object","properties":{"records":{"type":"integer"},"parseErrors":{"type":"integer"},"parseWarnings":{"type":"integer"},"validationErrors":{"type":"integer"},"excludedRecords":{"type":"integer","description":"Records left out of the outputs, with a diagnostic each."},"lockedForms":{"type":"integer","description":"Forms not paid for yet."}},"required":["records","parseErrors","parseWarnings","validationErrors","excludedRecords","lockedForms"]},"quote":{"type":"object","properties":{"totalCents":{"type":"integer","description":"What filing the unpaid forms costs now."},"byTaxYear":{"type":"array","items":{"type":"object","properties":{"taxYear":{"type":"integer"},"forms":{"type":"integer"},"quoteCents":{"type":"integer"}},"required":["taxYear","forms","quoteCents"]}},"balanceCents":{"type":"integer","description":"The account's credit balance."}},"required":["totalCents","byTaxYear","balanceCents"]},"transmissions":{"type":"array","items":{"$ref":"#/components/schemas/Transmission"}},"preview":{"oneOf":[{"type":"null"},{"type":"object","properties":{"recordTotal":{"type":"integer","description":"Records in the source file."},"convertedRecords":{"type":"integer"},"truncated":{"type":"boolean","description":"True when records were left out. Such a file never files or downloads."},"message":{"type":["string","null"]}},"required":["recordTotal","convertedRecords","truncated","message"]}],"description":"Set when an account without a license converted the file as a preview."}},"required":["id","status","stage","children","counts","quote","transmissions","preview"]},"Validation":{"type":"object","properties":{"source":{"type":"string","description":"How the input was read: `json`, `fire`, `csv`, `xlsx` or `xml`."},"recordCount":{"type":"integer"},"counts":{"type":"object","properties":{"parseErrors":{"type":"integer"},"validationErrors":{"type":"integer"},"warnings":{"type":"integer"},"infos":{"type":"integer"},"excludedRecords":{"type":"integer"}},"required":["parseErrors","validationErrors","warnings","infos","excludedRecords"]},"readyToConvert":{"type":"boolean","description":"True when the file would convert to fileable XML as is."},"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/Diagnostic"}},"diagnosticsTruncated":{"type":"boolean"},"preview":{"type":"object","properties":{"recordTotal":{"type":"integer"},"recordsChecked":{"type":"integer"}},"required":["recordTotal","recordsChecked"]},"note":{"type":"string","description":"A sentence about what was left out or why the layout was not read."}},"required":["source","recordCount","counts","readyToConvert","diagnostics","diagnosticsTruncated"]},"Form1099Record":{"type":"object","properties":{"formType":{"type":"string","enum":["NEC","MISC","INT","DIV","R","K","S"],"description":"K is 1099-B."},"taxYear":{"type":"integer"},"payer":{"$ref":"#/components/schemas/Party"},"payee":{"$ref":"#/components/schemas/Party"},"amounts":{"type":"object","description":"Dollar amounts keyed by Pub 1220 payment amount code (`1`-`9`, `A`-`J`, no `I`), not by paper box number. For example 1099-DIV federal withholding is code `A`.","additionalProperties":{"type":"number"}},"corrected":{"type":"boolean"},"voidReturn":{"type":"boolean"},"prevUniqueRecordId":{"type":"string","description":"UniqueRecordId of the accepted return a correction or void replaces."},"accountNumber":{"type":"string"},"secondTinNotice":{"type":"boolean"},"fatcaFilingRequirement":{"type":"boolean"},"stateWithholding":{"type":"array","items":{"type":"object","properties":{"state":{"type":"string","description":"USPS state code."},"stateId":{"type":"string","description":"Payer's state ID number."},"stateTax":{"type":"number"},"stateIncome":{"type":"number"},"localTax":{"type":"number"},"specialDataEntries":{"type":"string"}},"required":["state","stateId","stateTax"]}},"cfsfStates":{"type":"array","items":{"type":"string","description":"USPS state code."},"description":"Combined Federal/State Filing elections."},"form1099R":{"type":"object","properties":{"distributionCode":{"type":"string","description":"Box 7 code."},"taxableAmountNotDetermined":{"type":"boolean"},"totalDistribution":{"type":"boolean"},"iraSepSimple":{"type":"boolean"},"totalDistributionPercent":{"type":"integer","description":"Box 9a, 1-99. Leave it out for 100."},"firstYearDesignatedRoth":{"type":"integer","description":"Box 11, a four-digit year."},"paymentDate":{"type":"string","description":"`YYYY-MM-DD`."}},"required":["distributionCode"]},"foreignTaxCountry":{"type":"string","description":"IRS country code for foreign tax paid (INT code 6, DIV code C)."},"twoTransactionSecondStep":{"type":"boolean","description":"The second record of a two-transaction correction."},"correctsSubmissionId":{"type":"string","description":"The IRISfile submission this record corrects."},"cfsfElectionSupplied":{"type":"boolean","description":"Set by the parsers. Leave it out."},"form1099B":{"type":"object","properties":{"propertyDesc":{"type":"string","description":"Box 1a description of property."},"cusip":{"type":"string","description":"Up to 9 letters and digits."},"form8949Code":{"type":"string","enum":["A","B","D","E","X"]},"acquiredDate":{"type":"string","description":"Box 1b, `YYYY-MM-DD`."},"soldDate":{"type":"string","description":"Box 1c, `YYYY-MM-DD`."},"shortTerm":{"type":"boolean"},"longTerm":{"type":"boolean"},"ordinary":{"type":"boolean"},"collectibles":{"type":"boolean"},"qof":{"type":"boolean"},"noncoveredSecurity":{"type":"boolean"},"grossProceeds":{"type":"boolean"},"netProceeds":{"type":"boolean"},"lossNotAllowed":{"type":"boolean"},"basisReported":{"type":"boolean"}},"required":["propertyDesc"],"description":"1099-B fields that are not amounts. A K record without it is not fileable."},"form1099S":{"type":"object","properties":{"closingDate":{"type":"string","description":"Box 1, `YYYY-MM-DD`."},"addressOrLegalDesc":{"type":"string","description":"Box 3."},"transferorReceivedPropertyOrServices":{"type":"boolean"},"transferorForeignPerson":{"type":"boolean"},"cashGrossProceeds":{"type":"number"},"digitalAssetGrossProceeds":{"type":"number"},"digitalAssetType":{"type":"string"},"digitalAssetName":{"type":"string"},"digitalAssetUnits":{"type":"string"},"digitalAssetAcquiredDate":{"type":"string","description":"`YYYY-MM-DD`."}},"required":["closingDate","addressOrLegalDesc"],"description":"1099-S fields that are not amounts. An S record without it is not fileable."}},"required":["formType","taxYear","payer","payee","amounts","corrected"],"description":"One return in IRISfile's record model. A record missing a required field, or with a field of the wrong type, answers 400 `invalid_request`. The validator then checks the values."},"Party":{"type":"object","properties":{"tin":{"type":"string","description":"9 digits; hyphens allowed."},"tinType":{"type":"string","enum":["EIN","SSN","ITIN","ATIN","QI-EIN","UND","UNKNOWN"]},"name":{"type":"string"},"name2":{"type":"string"},"nameType":{"type":"string","enum":["B","I"],"description":"Business or individual."},"individualName":{"type":"object","properties":{"firstName":{"type":"string"},"middleName":{"type":"string"},"lastName":{"type":"string"},"suffix":{"type":"string"}},"required":["firstName","lastName"]},"address":{"type":"string"},"address2":{"type":"string","description":"Second address line."},"city":{"type":"string"},"state":{"type":"string","description":"USPS state code."},"zip":{"type":"string"},"phone":{"type":"string","description":"Payer only."},"foreignAddress":{"type":"boolean","description":"Payee only."},"foreignCountry":{"type":"string","description":"Payee only."}},"required":["tin","tinType","name","address","city","state","zip"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"environment":{"type":"string","enum":["sandbox","production"]},"secretLast4":{"type":"string","description":"The last 4 characters of the signing secret."},"createdAt":{"type":"string","description":"Timestamp with time zone, as Postgres prints it (for example `2026-10-21 14:03:22.5+00`)."},"lastDelivery":{"oneOf":[{"type":"null"},{"type":"object","properties":{"status":{"type":"string","enum":["pending","delivered","dead","cancelled"]},"statusCode":{"type":["integer","null"]},"at":{"type":["string","null"],"description":"Timestamp with time zone, as Postgres prints it (for example `2026-10-21 14:03:22.5+00`)."}},"required":["status","statusCode","at"]}]}},"required":["id","url","description","environment","secretLast4","createdAt","lastDelivery"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","dead","cancelled"]},"attempts":{"type":"integer"},"nextAttemptAt":{"type":["string","null"],"description":"Timestamp with time zone, as Postgres prints it (for example `2026-10-21 14:03:22.5+00`)."},"lastAttemptAt":{"type":["string","null"],"description":"Timestamp with time zone, as Postgres prints it (for example `2026-10-21 14:03:22.5+00`)."},"lastStatusCode":{"type":["integer","null"]},"lastError":{"type":["string","null"],"description":"A short code or redacted snippet of the response."},"deliveredAt":{"type":["string","null"],"description":"Timestamp with time zone, as Postgres prints it (for example `2026-10-21 14:03:22.5+00`)."},"createdAt":{"type":"string","description":"Timestamp with time zone, as Postgres prints it (for example `2026-10-21 14:03:22.5+00`)."}},"required":["id","eventId","eventType","status","attempts","nextAttemptAt","lastAttemptAt","lastStatusCode","lastError","deliveredAt","createdAt"]},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"Stable across retries. Dedupe on it.","format":"uuid"},"type":{"type":"string"},"created":{"type":"string","format":"date-time"},"apiVersion":{"type":"string","description":"Payload contract version, currently `2026-10-21`."},"environment":{"type":"string","enum":["sandbox","production"]},"data":{"type":"object"}},"required":["id","type","created","apiVersion","environment","data"]},"SubmissionConvertedData":{"type":"object","properties":{"submission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parentId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string"},"stage":{"type":"string","enum":["ready_to_file","needs_fixing","split","failed"]},"taxYear":{"type":["integer","null"]},"counts":{"type":"object","properties":{"records":{"type":"integer"},"parseErrors":{"type":"integer"},"validationErrors":{"type":"integer"},"warnings":{"type":"integer"},"exportExclusions":{"type":"integer"}},"required":["records","parseErrors","validationErrors","warnings","exportExclusions"]},"children":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","parentId","status","stage","taxYear","counts","children"]}},"required":["submission"]},"TransmissionEventData":{"type":"object","properties":{"submission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parentId":{"type":["string","null"],"format":"uuid"}},"required":["id","parentId"]},"transmission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"taxYear":{"type":["integer","null"]},"receiptId":{"type":["string","null"]},"ackCode":{"type":["string","null"],"enum":["A","E","P","R",null]},"irsStatus":{"type":["string","null"],"description":"Accepted, Accepted with Errors, Partially Accepted or Rejected."},"errorCount":{"type":"integer","description":"Number of IRS errors on the acknowledgement. On `transmission.acknowledged` only."}},"required":["id","sequence","taxYear","receiptId","ackCode","irsStatus"]},"reason":{"type":"string","enum":["submit_refused","ack_timeout"],"description":"On `transmission.failed` only."}},"required":["submission","transmission"]}}}}