Developer workspace API documentation
Sandbox
Developer documentation

TaxFileAPI reference

Explore the IRIS transmission sandbox, test credits, TY2026 Tax Returns preparation, and provider verification contracts. Live TaxFileAPI filing is awaiting activation.

Quickstart

  1. Sign into the sandbox and generate a sandbox key in the developer console.
  2. Use the cURL example for an immediate synthetic acknowledgment, or omit the sandbox approval header to receive a browser approval link.
  3. Poll the returned status_url using the same key. Check the record-level errors and retry a request with its original idempotency key.
curl -sS --fail-with-body https://www.taxfileapi.com/v1/transmissions \
  -H "Authorization: Bearer $TAXFILEAPI_SANDBOX_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: sandbox-quickstart-001' \
  -H 'X-TaxFileAPI-Sandbox-Approve: true' \
  --data '{"form":"1099-NEC","tax_year":2026,"header":{"payer_ref":"demo-payer"},"records":[{"record_id":"demo-001","fields":{"recipient_ref":"demo-recipient","nonemployee_compensation":"1250.00"}},{"record_id":"demo-002","fields":{"recipient_ref":"demo-recipient","nonemployee_compensation":"870.00"}}],"sandbox_scenario":"accepted"}'

New sandbox accounts start with two test credits. Add test credits if an approved batch returns 402.

Authentication and environments

Browser-only operations. Sign into the sandbox for key creation, wallet actions and batch approval.

Server calls. Discovery and fixture endpoints are public. Batch submission and status require Authorization: Bearer <sandbox key>. Sandbox keys expire after 24 hours and are not production credentials.

Errors. API errors use error.code and error.message. Field validation can add error.details. The browser approval endpoint returns HTML when the test wallet balance is insufficient.

Discovery

GET/v1/iris/filing-season

Get IRIS filing season status

Check TY2026 IRS opening expectations, TaxFileAPI live status, and the planned payment method.

Availability
Available
Authentication
None

Responses

200Current launch status
application/json · FilingSeason
Example response
{
  "channel": "iris",
  "tax_year": 2026,
  "processing_year": 2027,
  "sandbox": {
    "available": true,
    "price_cents": 0,
    "synthetic_only": true
  },
  "production": {
    "status": "awaiting_launch",
    "live_transmission_enabled": false,
    "expected_irs_opening_month": "2027-01",
    "confirmed_irs_opening_at": null,
    "payment_method": "prepaid_account_credits"
  },
  "irs_source_url": "https://www.irs.gov/pub/irs-efile/iris-working-group-meeting-10142026.pdf"
}
GET/v1/iris/forms

List the IRIS form catalog

List supported sandbox form-and-year pairs, upstream input-schema links and account-credit pricing rules.

Availability
Available
Authentication
None

Responses

200IRIS catalog
application/json · IRISCatalog
GET/v1/iris/schema

Get an IRIS form input schema

Fetch the input schema for one listed form and tax year. Schema availability is distinct from production eligibility.

Availability
Available
Authentication
None

Parameters

  • tax_year · query · required · 2025, 2026
  • form · query · required · "1042-S", "1097-BTC", "1098", "1098-C", "1098-E", "1098-F", "1098-Q", "1098-T"…

Responses

200Input schema
application/json · IRISFormSchema
404Form or year unavailable
application/json · Error
503Schema temporarily unavailable
application/json · Error

IRIS batches

POST/v1/transmissions

Submit an IRIS batch fixture

Submit 1–50 synthetic records, up to 24,000 bytes. Use unique demo-prefixed record IDs. 1099-NEC uses nonemployee_compensation as a positive decimal string. Other forms use fixture_ref. Partial acceptance needs at least two records.

Availability
Sandbox
Authentication
Sandbox bearer key

Parameters

  • Idempotency-Key · header · required · string
  • X-TaxFileAPI-Sandbox-Approve · header · optional · "true" — Explicit approval for synthetic quickstart calls.

Request body

application/json · TransmissionInput

{
  "form": "1099-NEC",
  "tax_year": 2026,
  "header": {
    "payer_ref": "demo-payer"
  },
  "records": [
    {
      "record_id": "demo-001",
      "fields": {
        "recipient_ref": "demo-recipient",
        "nonemployee_compensation": "1250.00"
      }
    },
    {
      "record_id": "demo-002",
      "fields": {
        "recipient_ref": "demo-recipient",
        "nonemployee_compensation": "870.00"
      }
    }
  ],
  "sandbox_scenario": "accepted"
}

Responses

200Identical retry
application/json · Transmission
201Batch created
application/json · Transmission
400Invalid key or JSON
application/json · Error
401Invalid bearer key
application/json · Error
402Insufficient simulated credits. Add credits and retry with the original key.
application/json · CreditError
409Idempotency conflict
application/json · Error
413Request too large
application/json · Error
415Unsupported media type
application/json · Error
422Field validation failed
application/json · Error
503Production or workspace unavailable
application/json · Error
GET/v1/transmissions/{id}

Read status and acknowledgment

Poll with the same sandbox bearer key that created the batch. The delayed fixture spends six seconds queued after approval. The approval URL is null in this response.

Availability
Sandbox
Authentication
Sandbox bearer key

Parameters

  • id · path · required · string

Responses

200Transmission found
application/json · Transmission
401Invalid bearer key
application/json · Error
404Transmission not found
application/json · Error
503Production or workspace unavailable
application/json · Error

Keys, approvals and credits

POST/v1/sandbox/keys

Issue a sandbox key

Generate a 24-hour key in the signed-in developer console. The response contains the key and an optional webhook secret. Browser POST must be same-origin.

Availability
Sandbox
Authentication
Signed-in TaxFileAPI sandbox session

Responses

201Key issued
application/json · SandboxKey
401Sign-in required
application/json · Error
403Same-origin required
application/json · Error
503Sandbox unavailable
application/json · Error
GET/approve/{token}

View the hosted approval page

Open the approval_url returned on submission. The link is sensitive and expires with the sandbox key.

Availability
Sandbox
Authentication
Approval URL token

Parameters

  • token · path · required · string

Responses

200Hosted review page
text/html · string
404Expired or invalid link
application/json · Error
503Sandbox unavailable
application/json · Error
POST/approve/{token}

Approve with sandbox credits

Use the hosted same-origin form while signed in as the wallet owner. A successful transition applies one test credit per record.

Availability
Sandbox
Authentication
Signed-in TaxFileAPI sandbox session

Parameters

  • token · path · required · string

Request body

application/x-www-form-urlencoded · object

Responses

303Redirect to the review page
Headers · Location
400Confirmation required
application/json · Error
402Insufficient test credits on the review page
text/html · string
403Wrong origin or wallet owner
application/json · Error
404Expired or invalid link
application/json · Error
409Legacy batch requires a fresh sandbox key
application/json · Error
415Expected browser form encoding
application/json · Error
503Sandbox unavailable
application/json · Error
GET/v1/sandbox/credits

Read sandbox credits

Read the signed-in account’s simulated credit wallet. Keys issued to the same account share the wallet.

Availability
Sandbox
Authentication
Signed-in TaxFileAPI sandbox session

Responses

200Balance
application/json · SandboxWallet
Example response
{
  "environment": "sandbox",
  "available": 2,
  "payment_charged": false
}
401Sign-in required
application/json · Error
503Wallet unavailable
application/json · Error
POST/v1/sandbox/credits/topups

Add sandbox credits

Add up to 2,000 test credits per request from a same-origin signed-in browser. The operation has no Stripe payment.

Availability
Sandbox
Authentication
Signed-in TaxFileAPI sandbox session

Parameters

  • Idempotency-Key · header · required · string — Reuse the original key for an identical retry. Use a new key when the request changes.

Request body

application/json · SandboxTopUp

{
  "quantity": 100
}

Responses

200Identical retry
application/json · SandboxWallet
201Top-up applied
application/json · SandboxWallet
400Invalid JSON or request
application/json · Error
401Sign-in required
application/json · Error
403Same-origin required
application/json · Error
409Top-up key reused with a different quantity
application/json · Error
413Request size limit exceeded
application/json · Error
415Content-Type must be application/json
application/json · Error
422Invalid fields or fixture
application/json · Error
503Wallet unavailable
application/json · Error

Single-fixture simulator

GET/v1/sandbox/forms

List single-fixture forms

Discover form fixtures for individual simulated IRIS requests.

Availability
Sandbox
Authentication
None

Responses

200Grouped fixture catalog
application/json · SingleFixtureCatalog
POST/v1/sandbox/transmissions

Submit a single IRIS fixture

Submit one IRIS fixture of up to 1,024 bytes. Every call generates a new simulated receipt. No wallet or batch approval is involved.

Availability
Sandbox
Authentication
None

Request body

application/json · SingleFixtureInput

{
  "channel": "iris",
  "form": "1099-NEC",
  "scenario": "accepted"
}

Responses

202Simulated receipt
application/json · SingleReceipt
Headers · Location
400Invalid JSON or request
application/json · Error
409MeF transmission is in development
application/json · Error
413Request size limit exceeded
application/json · Error
415Content-Type must be application/json
application/json · Error
422Invalid fields or fixture
application/json · Error
GET/v1/sandbox/acknowledgments/{receipt_id}

Get a single-fixture acknowledgment

Fetch the acknowledgment using the receipt from the simulator. A pending fixture remains pending. Older simulator receipts may identify MeF.

Availability
Sandbox
Authentication
None

Parameters

  • receipt_id · path · required · string

Responses

200Simulated acknowledgment
application/json · SingleAcknowledgment
404Invalid receipt
application/json · Error

Tax Returns preparation

GET/v1/sandbox/tax-returns

List TY2026 MeF prep fixtures

List TY2026 MeF form and fixture options. Production remains disabled.

Availability
Sandbox
Authentication
None

Responses

200MeF prep catalog
application/json · MeFCatalog
POST/v1/sandbox/tax-returns

Prepare a synthetic MeF draft

Prepare a synthetic TY2026 draft preview, up to 2,048 bytes. The missing-information fixture returns a successful response with findings. The result is a simulation.

Availability
Sandbox
Authentication
None

Request body

application/json · MeFFixture

{
  "tax_year": 2026,
  "form": "1040",
  "fixture": "complete"
}

Responses

200Synthetic draft preview or preparation findings
application/json · MeFDraft
400Invalid JSON or request
application/json · Error
413Request size limit exceeded
application/json · Error
415Content-Type must be application/json
application/json · Error
422Invalid fields or fixture
application/json · Error

Provider verification

GET/v1/provider-applications

List your provider applications

When enabled, lists up to 30 applications belonging to the signed-in account and whether review is configured.

Availability
Paused · production onboarding
Authentication
Signed-in TaxFileAPI sandbox session

Responses

200Provider applications
application/json · ProviderApplications
401Sign-in required
application/json · Error
409Provider preview is paused or an existing record changed
application/json · Error
503Verification service unavailable
application/json · Error
POST/v1/provider-applications

Submit a provider application

When enabled, submits an ERO or Online Provider application for review. Use a secure evidence reference. Returned EFINs are masked.

Availability
Paused · production onboarding
Authentication
Signed-in TaxFileAPI sandbox session

Request body

application/json · ProviderApplicationInput

Responses

201Application is pending review
application/json · ProviderApplication
400Invalid JSON or request
application/json · Error
401Sign-in required
application/json · Error
403Same-origin required
application/json · Error
409Provider preview is paused or an existing record changed
application/json · Error
413Request size limit exceeded
application/json · Error
415Content-Type must be application/json
application/json · Error
422Invalid fields or fixture
application/json · Error
429Account application limit reached
application/json · Error
503Verification service unavailable
application/json · Error
POST/v1/provider-applications/{id}/review

Record a provider verification decision

When enabled, an assigned reviewer records a decision after comparing the applicant’s active role and EFIN with IRS evidence. Verified status expires after 90 days.

Availability
Paused · production onboarding
Authentication
Assigned reviewer account

Parameters

  • id · path · required · string

Request body

application/json · ProviderReview

Responses

200Decision recorded
application/json · ProviderApplication
400Invalid JSON or request
application/json · Error
401Sign-in required
application/json · Error
403Assigned reviewer or same-origin required
application/json · Error
404Application not found
application/json · Error
409Provider preview is paused or an existing record changed
application/json · Error
413Request size limit exceeded
application/json · Error
415Content-Type must be application/json
application/json · Error
422Invalid fields or fixture
application/json · Error
503Verification service unavailable
application/json · Error
POST/v1/provider-verification/check

Verify provider eligibility

When enabled, checks that the provider record belongs to the authenticated owner and matches the role and EFIN. Verification must remain active.

Availability
Paused · production onboarding
Authentication
Filing-service bearer

Request body

application/json · ProviderCheckInput

Responses

200Active verification
application/json · ProviderCheck
400Invalid JSON or request
application/json · Error
403Service credential invalid or provider unverifiable
application/json · Error
409Provider preview is paused or an existing record changed
application/json · Error
413Request size limit exceeded
application/json · Error
415Content-Type must be application/json
application/json · Error
422Invalid fields or fixture
application/json · Error
503Verification service unavailable
application/json · Error

Webhooks

transmission.acknowledged

Optional outbound sandbox event. An operator configures one HTTPS destination. When enabled, a newly issued sandbox key includes the signing secret.

Parse TaxFileAPI-Signature: t=<unix seconds>,v1=<hex digest>. Use HMAC-SHA256 with the signing secret over the timestamp, one period, and the exact raw UTF-8 body. Compare digests safely, check timestamp freshness, deduplicate by event id, and return a 2xx only after accepting the event.

{
  "id": "evt_tx_example",
  "type": "transmission.acknowledged",
  "data": {
    "transmission_id": "tx_example",
    "environment": "sandbox",
    "status": "accepted"
  }
}

The example shows selected fields. The full data object follows the Transmission schema. A later status request can retry delivery after a failure. Use polling for reconciliation.

Request and response schemas

Open a model to inspect each field, accepted value, and constraint.

TransmissionInput
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "form": {
      "type": "string",
      "enum": [
        "1042-S",
        "1097-BTC",
        "1098",
        "1098-C",
        "1098-E",
        "1098-F",
        "1098-Q",
        "1098-T",
        "1098-VLI",
        "1099-A",
        "1099-B",
        "1099-C",
        "1099-CAP",
        "1099-DA",
        "1099-DIV",
        "1099-G",
        "1099-INT",
        "1099-K",
        "1099-LPS",
        "1099-LS",
        "1099-LTC",
        "1099-MISC",
        "1099-NEC",
        "1099-OID",
        "1099-PATR",
        "1099-Q",
        "1099-QA",
        "1099-R",
        "1099-S",
        "1099-SA",
        "1099-SB",
        "15397",
        "3921",
        "3922",
        "5498",
        "5498-ESA",
        "5498-QA",
        "5498-SA",
        "5498-TA",
        "8027",
        "8596",
        "8809",
        "8955-SSA",
        "W-2G"
      ],
      "description": "See GET /v1/iris/forms for form-by-year availability."
    },
    "tax_year": {
      "type": "integer",
      "enum": [
        2025,
        2026
      ]
    },
    "header": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "payer_ref": {
          "const": "demo-payer"
        }
      },
      "required": [
        "payer_ref"
      ]
    },
    "records": {
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "record_id": {
            "type": "string",
            "pattern": "^demo-[a-z0-9-]{1,40}$"
          },
          "fields": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "recipient_ref": {
                    "const": "demo-recipient"
                  },
                  "nonemployee_compensation": {
                    "type": "string",
                    "pattern": "^(?:0|[1-9][0-9]{0,7})\\.[0-9]{2}$"
                  }
                },
                "required": [
                  "recipient_ref",
                  "nonemployee_compensation"
                ]
              },
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "fixture_ref": {
                    "const": "demo-form-record"
                  }
                },
                "required": [
                  "fixture_ref"
                ]
              }
            ]
          }
        },
        "required": [
          "record_id",
          "fields"
        ]
      }
    },
    "sandbox_scenario": {
      "enum": [
        "accepted",
        "rejected",
        "partially_accepted",
        "delayed"
      ]
    }
  },
  "required": [
    "form",
    "tax_year",
    "header",
    "records",
    "sandbox_scenario"
  ]
}
CreditError
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "error": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "code": {
          "const": "insufficient_account_credits"
        },
        "message": {
          "type": "string"
        },
        "credits_required": {
          "type": "integer"
        },
        "transmission_id": {
          "type": "string"
        },
        "approval_url": {
          "type": "string"
        },
        "sandbox_wallet_url": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message",
        "credits_required",
        "transmission_id",
        "approval_url",
        "sandbox_wallet_url"
      ]
    }
  },
  "required": [
    "error"
  ]
}
Finding
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "code": {
      "type": "string"
    },
    "record_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "field": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "record_id",
    "field",
    "message"
  ]
}
Error
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "error": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Finding"
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "required": [
    "error"
  ]
}
Acknowledgment
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "enum": [
        "accepted",
        "rejected",
        "partially_accepted"
      ]
    },
    "simulated": {
      "const": true
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "record_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "accepted",
              "rejected"
            ]
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Finding"
            }
          }
        },
        "required": [
          "record_id",
          "status",
          "errors"
        ]
      }
    }
  },
  "required": [
    "status",
    "simulated",
    "records"
  ]
}
Transmission
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "transmission_id": {
      "type": "string"
    },
    "environment": {
      "const": "sandbox"
    },
    "status": {
      "enum": [
        "awaiting_approval",
        "queued",
        "accepted",
        "rejected",
        "partially_accepted"
      ]
    },
    "form": {
      "type": "string"
    },
    "tax_year": {
      "type": "integer"
    },
    "record_count": {
      "type": "integer"
    },
    "price": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "currency": {
          "const": "USD"
        },
        "amount_cents": {
          "const": 0
        }
      },
      "required": [
        "currency",
        "amount_cents"
      ]
    },
    "credits": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "required": {
          "type": "integer"
        },
        "applied": {
          "type": "integer"
        },
        "simulated": {
          "const": true
        }
      },
      "required": [
        "required",
        "applied",
        "simulated"
      ]
    },
    "approval_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "status_url": {
      "type": "string"
    },
    "receipt_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "acknowledgment": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/Acknowledgment"
        },
        {
          "type": "null"
        }
      ]
    },
    "sent_to_irs": {
      "const": false
    },
    "irs_acceptance_verified": {
      "const": false
    },
    "payment_charged": {
      "const": false
    }
  },
  "required": [
    "transmission_id",
    "environment",
    "status",
    "form",
    "tax_year",
    "record_count",
    "price",
    "credits",
    "approval_url",
    "status_url",
    "receipt_id",
    "acknowledgment",
    "sent_to_irs",
    "irs_acceptance_verified",
    "payment_charged"
  ]
}
FilingSeason
{
  "type": "object",
  "properties": {
    "channel": {
      "const": "iris"
    },
    "tax_year": {
      "type": "integer"
    },
    "processing_year": {
      "type": "integer"
    },
    "sandbox": {
      "type": "object",
      "properties": {
        "available": {
          "type": "boolean"
        },
        "price_cents": {
          "type": "integer"
        },
        "synthetic_only": {
          "type": "boolean"
        }
      },
      "required": [
        "available",
        "price_cents",
        "synthetic_only"
      ],
      "additionalProperties": false
    },
    "production": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string"
        },
        "live_transmission_enabled": {
          "type": "boolean"
        },
        "expected_irs_opening_month": {
          "type": "string"
        },
        "confirmed_irs_opening_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "payment_method": {
          "type": "string"
        }
      },
      "required": [
        "status",
        "live_transmission_enabled",
        "expected_irs_opening_month",
        "confirmed_irs_opening_at",
        "payment_method"
      ],
      "additionalProperties": false
    },
    "irs_source_url": {
      "type": "string"
    }
  },
  "required": [
    "channel",
    "tax_year",
    "processing_year",
    "sandbox",
    "production",
    "irs_source_url"
  ],
  "additionalProperties": false
}
IRISCatalog
{
  "type": "object",
  "properties": {
    "channel": {
      "const": "iris"
    },
    "filing_season_url": {
      "type": "string"
    },
    "forms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "form": {
            "type": "string"
          },
          "tax_year": {
            "type": "integer"
          },
          "schema_url": {
            "type": "string"
          },
          "sandbox_batch": {
            "type": "boolean"
          },
          "transmission_status": {
            "type": "string"
          },
          "account_credit_pricing": {
            "enum": [
              "per_record",
              "requires_form_specific_pricing"
            ]
          }
        },
        "required": [
          "form",
          "tax_year",
          "schema_url",
          "sandbox_batch",
          "transmission_status",
          "account_credit_pricing"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "channel",
    "filing_season_url",
    "forms"
  ],
  "additionalProperties": false
}
IRISFormSchema
{
  "type": "object",
  "properties": {
    "form": {
      "type": "string"
    },
    "tax_year": {
      "type": "integer"
    },
    "header": {
      "type": "object"
    },
    "record": {
      "type": "object"
    },
    "max_records": {
      "type": "integer"
    },
    "submission_group": {
      "type": "string"
    }
  },
  "required": [
    "form",
    "tax_year",
    "header",
    "record"
  ],
  "additionalProperties": false
}
SandboxKey
{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "webhook_secret": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "api_key",
    "expires_at",
    "webhook_secret"
  ],
  "additionalProperties": false
}
SandboxWallet
{
  "type": "object",
  "properties": {
    "environment": {
      "const": "sandbox"
    },
    "available": {
      "type": "integer"
    },
    "payment_charged": {
      "const": false
    }
  },
  "required": [
    "environment",
    "available",
    "payment_charged"
  ],
  "additionalProperties": false
}
SandboxTopUp
{
  "type": "object",
  "properties": {
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 2000
    }
  },
  "required": [
    "quantity"
  ],
  "additionalProperties": false
}
SingleFixtureCatalog
{
  "type": "object",
  "properties": {
    "environment": {
      "const": "sandbox"
    },
    "channels": {
      "type": "object",
      "properties": {
        "iris": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "forms": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "name",
              "forms"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "iris"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "environment",
    "channels"
  ],
  "additionalProperties": false
}
SingleFixtureInput
{
  "type": "object",
  "properties": {
    "channel": {
      "const": "iris"
    },
    "form": {
      "enum": [
        "1099-NEC",
        "1099-MISC",
        "1099-INT",
        "1099-DIV",
        "1099-K",
        "1099-DA",
        "1099-A",
        "1099-B",
        "1099-C",
        "1099-CAP",
        "1099-G",
        "1099-LPS",
        "1099-LS",
        "1099-LTC",
        "1099-OID",
        "1099-PATR",
        "1099-Q",
        "1099-QA",
        "1099-R",
        "1099-S",
        "1099-SA",
        "1099-SB",
        "1098",
        "1098-C",
        "1098-E",
        "1098-F",
        "1098-Q",
        "1098-T",
        "1098-VLI",
        "5498",
        "5498-ESA",
        "5498-QA",
        "5498-SA",
        "5498-TA",
        "1042-S",
        "1097-BTC",
        "3921",
        "3922",
        "8027",
        "8596",
        "8809",
        "8955-SSA",
        "15397",
        "W-2G"
      ]
    },
    "scenario": {
      "enum": [
        "accepted",
        "rejected",
        "pending"
      ]
    }
  },
  "required": [
    "channel",
    "form",
    "scenario"
  ],
  "additionalProperties": false
}
SingleReceipt
{
  "type": "object",
  "properties": {
    "receipt_id": {
      "type": "string"
    },
    "acknowledgment_url": {
      "type": "string"
    },
    "environment": {
      "const": "sandbox"
    },
    "status": {
      "const": "received"
    },
    "sent_to_irs": {
      "const": false
    },
    "payment_charged": {
      "const": false
    }
  },
  "required": [
    "receipt_id",
    "acknowledgment_url",
    "environment",
    "status",
    "sent_to_irs",
    "payment_charged"
  ],
  "additionalProperties": false
}
SingleAcknowledgment
{
  "type": "object",
  "properties": {
    "receipt_id": {
      "type": "string"
    },
    "environment": {
      "const": "sandbox"
    },
    "channel": {
      "enum": [
        "iris",
        "mef"
      ]
    },
    "form": {
      "type": "string"
    },
    "status": {
      "enum": [
        "accepted",
        "rejected",
        "pending"
      ]
    },
    "sent_to_irs": {
      "const": false
    },
    "irs_acceptance_verified": {
      "const": false
    },
    "payment_charged": {
      "const": false
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "receipt_id",
    "environment",
    "channel",
    "form",
    "status",
    "sent_to_irs",
    "irs_acceptance_verified",
    "payment_charged"
  ],
  "additionalProperties": false
}
MeFCatalog
{
  "type": "object",
  "properties": {
    "environment": {
      "const": "sandbox"
    },
    "channel": {
      "const": "mef"
    },
    "tax_year": {
      "const": 2026
    },
    "groups": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "forms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "label",
          "forms"
        ],
        "additionalProperties": false
      }
    },
    "fixtures": {
      "type": "array",
      "items": {
        "enum": [
          "complete",
          "missing_information"
        ]
      }
    },
    "production": {
      "type": "object",
      "properties": {
        "enabled": {
          "const": false
        },
        "credential_verification_required": {
          "const": true
        },
        "accepted_provider_roles": {
          "type": "array",
          "items": {
            "enum": [
              "ero",
              "online_provider"
            ]
          }
        }
      },
      "required": [
        "enabled",
        "credential_verification_required",
        "accepted_provider_roles"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "environment",
    "channel",
    "tax_year",
    "groups",
    "fixtures",
    "production"
  ],
  "additionalProperties": false
}
MeFFixture
{
  "type": "object",
  "properties": {
    "tax_year": {
      "const": 2026
    },
    "form": {
      "enum": [
        "1040",
        "1040-NR",
        "1041",
        "2350",
        "4868",
        "9465",
        "1065",
        "1120",
        "1120-S",
        "1120-F",
        "1120-POL",
        "1042",
        "7004",
        "990",
        "990-EZ",
        "990-PF",
        "990-T",
        "4720",
        "5227",
        "5330",
        "8868",
        "8038-CP",
        "940",
        "941",
        "941-X",
        "943",
        "943-X",
        "944",
        "944-X",
        "945",
        "945-X",
        "94x-PIN",
        "720",
        "2290",
        "8849",
        "1045-IND",
        "1045-EST",
        "1139",
        "56",
        "706",
        "709",
        "8892"
      ]
    },
    "fixture": {
      "enum": [
        "complete",
        "missing_information"
      ]
    }
  },
  "required": [
    "tax_year",
    "form",
    "fixture"
  ],
  "additionalProperties": false
}
MeFDraft
{
  "type": "object",
  "properties": {
    "draft_id": {
      "type": "string"
    },
    "channel": {
      "const": "mef"
    },
    "environment": {
      "const": "sandbox"
    },
    "form": {
      "type": "string"
    },
    "form_family": {
      "type": "string"
    },
    "tax_year": {
      "const": 2026
    },
    "status": {
      "enum": [
        "prepared",
        "needs_information"
      ]
    },
    "inputs": {
      "type": "object",
      "properties": {
        "filer_ref": {
          "type": [
            "string",
            "null"
          ]
        },
        "tax_year": {
          "const": 2026
        },
        "form": {
          "type": "string"
        }
      },
      "required": [
        "filer_ref",
        "tax_year",
        "form"
      ],
      "additionalProperties": false
    },
    "findings": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Finding"
      }
    },
    "simulation": {
      "type": "object",
      "properties": {
        "irs_schema_validated": {
          "const": false
        },
        "return_calculated": {
          "const": false
        },
        "sent_to_irs": {
          "const": false
        },
        "payment_charged": {
          "const": false
        }
      },
      "required": [
        "irs_schema_validated",
        "return_calculated",
        "sent_to_irs",
        "payment_charged"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "draft_id",
    "channel",
    "environment",
    "form",
    "form_family",
    "tax_year",
    "status",
    "inputs",
    "findings",
    "simulation"
  ],
  "additionalProperties": false
}
ProviderApplicationInput
{
  "type": "object",
  "properties": {
    "legal_name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 160
    },
    "contact_email": {
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "role": {
      "enum": [
        "ero",
        "online_provider"
      ]
    },
    "efin": {
      "type": "string",
      "pattern": "^[0-9]{6}$"
    },
    "evidence_ref": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.:-]{3,79}$"
    }
  },
  "required": [
    "legal_name",
    "contact_email",
    "role",
    "efin",
    "evidence_ref"
  ],
  "additionalProperties": false
}
ProviderApplication
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "legal_name": {
      "type": "string"
    },
    "contact_email": {
      "type": "string"
    },
    "role": {
      "enum": [
        "ero",
        "online_provider"
      ]
    },
    "efin_last_four": {
      "type": "string"
    },
    "status": {
      "enum": [
        "pending",
        "verified",
        "expired",
        "rejected",
        "revoked"
      ]
    },
    "submitted_at": {
      "type": "string"
    },
    "verified_until": {
      "type": [
        "string",
        "null"
      ]
    },
    "review_reason": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "id",
    "legal_name",
    "contact_email",
    "role",
    "efin_last_four",
    "status",
    "submitted_at",
    "verified_until",
    "review_reason"
  ],
  "additionalProperties": false
}
ProviderApplications
{
  "type": "object",
  "properties": {
    "applications": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ProviderApplication"
      }
    },
    "review_configured": {
      "type": "boolean"
    }
  },
  "required": [
    "applications",
    "review_configured"
  ],
  "additionalProperties": false
}
ProviderReview
{
  "type": "object",
  "properties": {
    "decision": {
      "enum": [
        "verified",
        "rejected",
        "revoked"
      ]
    },
    "reason": {
      "type": "string",
      "minLength": 12,
      "maxLength": 400
    },
    "matched_efin": {
      "type": "string"
    },
    "confirmed_active_role": {
      "type": "string"
    },
    "verified_evidence_ref": {
      "type": "string"
    },
    "matched_legal_name": {
      "type": "string"
    }
  },
  "required": [
    "decision",
    "reason",
    "matched_efin",
    "confirmed_active_role",
    "verified_evidence_ref",
    "matched_legal_name"
  ],
  "additionalProperties": false
}
ProviderCheckInput
{
  "type": "object",
  "properties": {
    "provider_id": {
      "type": "string",
      "pattern": "^prov_[a-f0-9]{32}$"
    },
    "owner_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "role": {
      "enum": [
        "ero",
        "online_provider"
      ]
    },
    "efin": {
      "type": "string",
      "pattern": "^[0-9]{6}$"
    }
  },
  "required": [
    "provider_id",
    "owner_id",
    "role",
    "efin"
  ],
  "additionalProperties": false
}
ProviderCheck
{
  "type": "object",
  "properties": {
    "provider_id": {
      "type": "string"
    },
    "verified": {
      "const": true
    },
    "verified_until": {
      "type": "string"
    }
  },
  "required": [
    "provider_id",
    "verified",
    "verified_until"
  ],
  "additionalProperties": false
}