{
  "openapi": "3.1.0",
  "info": {
    "title": "e1099f API",
    "version": "2026-06-15",
    "summary": "File 1099s, W-2s and more — from your code.",
    "description": "REST over HTTPS, JSON in and out, OAuth 2.0. Every write is idempotent, every environment is app-scoped, and nothing reaches the IRS from sandbox. Filed under one IRS-authorized transmitter, LEIRAD GROUP LLC.\n\nThe filing model is intake-then-pay: `POST /v1/payers/{payerId}/forms` (or a FIRE import) brings forms to `ready_to_file` and never charges; pricing, the cart and payment live under the Payments endpoints, and a form only reaches the IRS after `POST /v1/cart/pay`.\n\nForms are filled **scheme JSON** — the exact object `GET /v1/forms/{form}` hands you, keyed by the IRS's own IRIS element names — so you never touch internal box names.\n\nVersioned by date. Pin a version with the `API-Version` request header (an unknown value is a 400); a production request with no header uses the account's default version; every response echoes the serving version in the `API-Version` header. Current version: `2026-06-15`.",
    "contact": { "name": "e1099f developer support", "url": "https://e1099f.com/docs/api" },
    "termsOfService": "https://e1099f.com/legal/developer-terms"
  },
  "servers": [
    { "url": "https://api.e1099f.com", "description": "Production — real filings reach the IRS. Keys sk_live_…" },
    { "url": "https://sandbox.e1099f.com", "description": "Sandbox — deterministic, never reaches the IRS. Keys sk_sandbox_…" }
  ],
  "security": [ { "bearerAuth": [] }, { "oauth2": [] } ],
  "tags": [
    { "name": "Auth", "description": "OAuth 2.0 token exchange." },
    { "name": "Forms", "description": "Discover a form's shape, then file forms under a payer — intake only, never charges." },
    { "name": "Payers", "description": "The businesses you file on behalf of." },
    { "name": "Recipients", "description": "The payees a form is issued to." },
    { "name": "Cart", "description": "Stage ready-to-file forms, price them, and pay." },
    { "name": "Balance", "description": "Prepaid balance drawn before the card on file." },
    { "name": "Filings", "description": "Read a filed form, correct it, or void it before transmit." },
    { "name": "Extensions", "description": "Form 8809 extensions of time to file." },
    { "name": "TIN Match", "description": "Asynchronous IRS TIN matching (Pub 2108-A)." },
    { "name": "Documents", "description": "Copy B recipient statements and IRS acknowledgements." },
    { "name": "Orders", "description": "Paid orders and receipts." },
    { "name": "Webhooks", "description": "Endpoint registration and delivery history." },
    { "name": "Sandbox", "description": "Reset your deterministic sandbox company." }
  ],
  "paths": {
    "/oauth/token": {
      "post": {
        "tags": ["Auth"], "operationId": "createToken", "security": [],
        "summary": "Exchange client credentials for an access token",
        "description": "OAuth 2.0 `client_credentials` grant. Returns a short-lived bearer token scoped to the app's granted scopes.",
        "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": {
          "type": "object", "required": ["grant_type", "client_id", "client_secret"],
          "properties": {
            "grant_type": { "type": "string", "enum": ["client_credentials"] },
            "client_id": { "type": "string" },
            "client_secret": { "type": "string" },
            "scope": { "type": "string", "description": "Space-separated subset of the app's scopes." }
          } } } } },
        "responses": {
          "200": { "description": "A bearer token.", "content": { "application/json": { "schema": {
            "type": "object", "properties": {
              "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" },
              "expires_in": { "type": "integer", "example": 3600 }, "scope": { "type": "string" } } } } } },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/forms/{form}": {
      "get": {
        "tags": ["Forms"], "operationId": "getFormShape",
        "summary": "Get a form's scheme JSON for a tax year",
        "description": "The authoritative, schema-derived skeleton for a form — nested and keyed by IRIS element name, with a placeholder per leaf. Fill it and POST it to `/v1/payers/{payerId}/forms`. Generated from the IRS XSD, never hand-written, so it grows with the engine.",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [
          { "name": "form", "in": "path", "required": true, "schema": { "type": "string" }, "example": "1099-NEC" },
          { "name": "tax_year", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Defaults to the most recent filing year." }
        ],
        "responses": {
          "200": { "description": "The form's element list and filled-in-able scheme.", "content": { "application/json": { "schema": {
            "type": "object", "properties": {
              "object": { "type": "string", "example": "form_elements" },
              "form": { "type": "string", "example": "1099-NEC" },
              "tax_year": { "type": "integer" },
              "elements": { "type": "object", "additionalProperties": { "type": "string" }, "description": "element name → JSON type" },
              "formJson": { "type": "object", "description": "The schema-derived skeleton to fill and POST." } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "422": { "$ref": "#/components/responses/InvalidRequest" }
        }
      }
    },
    "/v1/payers/{payerId}/forms": {
      "post": {
        "tags": ["Forms"], "operationId": "fileFormsUnderPayer",
        "summary": "File one or many forms under a payer",
        "description": "Each form is a filled scheme JSON. Saved as `ready_to_file`; pass `addToCart: true` to stage in the cart. Intake only — never files and never charges. Send `Idempotency-Key` to make retries safe.",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "parameters": [
          { "$ref": "#/components/parameters/PayerId" },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerFormsIntake" } } } },
        "responses": {
          "201": { "description": "Per-form results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerFormsIntakeResult" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/InProgress" },
          "422": { "$ref": "#/components/responses/InvalidRequest" }
        }
      }
    },
    "/v1/payers/{payerId}/fire": {
      "post": {
        "tags": ["Forms"], "operationId": "importFireFile",
        "summary": "Import a Pub 1220 FIRE file under a payer",
        "description": "The migration door off the retiring IRS FIRE system. Raw request body (the file bytes), up to 12 MB. Parses every recipient and amount — including corrections — and brings forms to `ready_to_file`. Parses and imports; never files and never charges.",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "parameters": [
          { "$ref": "#/components/parameters/PayerId" },
          { "name": "addToCart", "in": "query", "required": false, "schema": { "type": "boolean" } }
        ],
        "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } },
        "responses": {
          "200": { "description": "What the file contained and what was imported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FireImportResult" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "413": { "description": "File exceeds 12 MB." },
          "422": { "$ref": "#/components/responses/InvalidRequest" }
        }
      }
    },
    "/v1/payers": {
      "get": {
        "tags": ["Payers"], "operationId": "listPayers", "summary": "List payers",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ],
        "responses": { "200": { "$ref": "#/components/responses/PayerList" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      },
      "post": {
        "tags": ["Payers"], "operationId": "createPayer", "summary": "Create a payer",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerInput" } } } },
        "responses": { "201": { "$ref": "#/components/responses/Payer" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/InvalidRequest" } }
      }
    },
    "/v1/payers/{id}": {
      "patch": {
        "tags": ["Payers"], "operationId": "updatePayer", "summary": "Update a payer",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerInput" } } } },
        "responses": { "200": { "$ref": "#/components/responses/Payer" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/v1/recipients": {
      "get": {
        "tags": ["Recipients"], "operationId": "listRecipients", "summary": "List recipients",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ],
        "responses": { "200": { "description": "A page of recipients." }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      },
      "post": {
        "tags": ["Recipients"], "operationId": "createRecipient", "summary": "Create a recipient",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientInput" } } } },
        "responses": { "201": { "description": "The created recipient." }, "422": { "$ref": "#/components/responses/InvalidRequest" } }
      }
    },
    "/v1/recipients/{id}": {
      "patch": {
        "tags": ["Recipients"], "operationId": "updateRecipient", "summary": "Update a recipient",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientInput" } } } },
        "responses": { "200": { "description": "The updated recipient." }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/v1/cart/details": {
      "get": { "tags": ["Cart"], "operationId": "getCart", "summary": "Read the cart with line items and totals",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "responses": { "200": { "description": "The cart, its items and priced totals." }, "401": { "$ref": "#/components/responses/Unauthorized" } } }
    },
    "/v1/cart/value": {
      "get": { "tags": ["Cart"], "operationId": "getCartValue", "summary": "Read the cart's total without line detail",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "responses": { "200": { "description": "The cart total." } } }
    },
    "/v1/cart/items": {
      "post": { "tags": ["Cart"], "operationId": "addCartItem", "summary": "Add a ready-to-file form to the cart",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": ["filing_id"], "properties": {
            "filing_id": { "type": "string", "format": "uuid" },
            "service": { "$ref": "#/components/schemas/Service" } } } } } },
        "responses": { "201": { "description": "The cart line item." }, "422": { "$ref": "#/components/responses/InvalidRequest" } } }
    },
    "/v1/cart/pay": {
      "post": { "tags": ["Cart"], "operationId": "payCart",
        "summary": "Pay the cart — the only endpoint that files to the IRS",
        "description": "Charges the cart (balance first, then the card on file) and transmits. Owner-only. The charge clears **before** the return is sent, so there is never a file-then-invoice gap. A decline returns `402` and nothing is filed. Idempotent: a paid cart returns its receipt with `already_paid`; racing an in-flight pay returns `409`.",
        "security": [ { "bearerAuth": ["payments:write"] } ],
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "responses": {
          "200": { "description": "A receipt for the paid, transmitted cart." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "description": "Payment declined — nothing was filed." },
          "403": { "description": "Caller is not the account Owner." },
          "409": { "$ref": "#/components/responses/InProgress" } } }
    },
    "/v1/prices": {
      "get": { "tags": ["Cart"], "operationId": "listPrices", "summary": "Current per-service pricing",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "responses": { "200": { "description": "Prices by service and volume bracket." } } }
    },
    "/v1/prices/quote": {
      "get": { "tags": ["Cart"], "operationId": "quotePrice", "summary": "Quote a price for a form count and service",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [
          { "name": "form", "in": "query", "schema": { "type": "string" } },
          { "name": "quantity", "in": "query", "schema": { "type": "integer" } },
          { "name": "service", "in": "query", "schema": { "$ref": "#/components/schemas/Service" } } ],
        "responses": { "200": { "description": "The quoted unit and total price." } } }
    },
    "/v1/balance": {
      "get": { "tags": ["Balance"], "operationId": "getBalance", "summary": "Read the prepaid balance",
        "security": [ { "bearerAuth": ["payments:read"] } ],
        "responses": { "200": { "description": "Current balance in cents." } } }
    },
    "/v1/balance/entries": {
      "get": { "tags": ["Balance"], "operationId": "listBalanceEntries", "summary": "Balance ledger history",
        "security": [ { "bearerAuth": ["payments:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ],
        "responses": { "200": { "description": "A page of ledger entries." } } }
    },
    "/v1/balance/top-ups": {
      "post": { "tags": ["Balance"], "operationId": "topUpBalance", "summary": "Add funds to the prepaid balance",
        "security": [ { "bearerAuth": ["payments:write"] } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": ["amount_cents"], "properties": { "amount_cents": { "type": "integer", "minimum": 1 } } } } } },
        "responses": { "201": { "description": "The recorded top-up." }, "402": { "description": "Charge declined." } } }
    },
    "/v1/filings": {
      "get": { "tags": ["Filings"], "operationId": "listFilings", "summary": "List filings",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" },
          { "name": "status", "in": "query", "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "A page of filings." } } }
    },
    "/v1/filings/{id}": {
      "get": { "tags": ["Filings"], "operationId": "getFiling", "summary": "Read a filing",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "The filing." }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "delete": { "tags": ["Filings"], "operationId": "voidFiling", "summary": "Void a filing before it is transmitted",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "The voided filing." }, "409": { "description": "Already transmitted — file a correction instead." } } }
    },
    "/v1/filings/{id}/corrections": {
      "post": { "tags": ["Filings"], "operationId": "correctFiling", "summary": "Correct an accepted filing",
        "description": "Creates a correction of an already-accepted return. The correction is brought to `ready_to_file` and priced like an original.",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "properties": { "jsonForm": { "type": "object" }, "addToCart": { "type": "boolean" }, "service": { "$ref": "#/components/schemas/Service" } } } } } },
        "responses": { "201": { "description": "The created correction." }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/v1/filings/{id}/ack": {
      "get": { "tags": ["Documents"], "operationId": "getFilingAck", "summary": "IRS acknowledgement for a filing",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "The acknowledgement, with raw IRS status passthrough." } } }
    },
    "/v1/filings/{id}/copy-b": {
      "get": { "tags": ["Documents"], "operationId": "getFilingCopyB", "summary": "Copy B recipient statement (PDF)",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "The Copy B PDF.", "content": { "application/pdf": {} } } } }
    },
    "/v1/extensions": {
      "get": { "tags": ["Extensions"], "operationId": "listExtensions", "summary": "List Form 8809 extensions",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "responses": { "200": { "description": "A page of extensions." } } },
      "post": { "tags": ["Extensions"], "operationId": "createExtension", "summary": "Request a Form 8809 extension of time",
        "description": "Extensions of time to file are free.",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "201": { "description": "The submitted extension." } } }
    },
    "/v1/extensions/{id}": {
      "get": { "tags": ["Extensions"], "operationId": "getExtension", "summary": "Read an extension",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "The extension." }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/v1/tin-match": {
      "get": { "tags": ["TIN Match"], "operationId": "listTinMatch", "summary": "List TIN match requests",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "responses": { "200": { "description": "A page of TIN match requests." } } },
      "post": { "tags": ["TIN Match"], "operationId": "createTinMatch", "summary": "Submit names/TINs for IRS matching",
        "description": "Asynchronous by design: Pub 2108-A caps interactive matching at 999/24h on one platform User ID. Poll the returned receipt for the result.",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "202": { "description": "Accepted; poll the receipt." } } }
    },
    "/v1/tin-match/{receiptId}": {
      "get": { "tags": ["TIN Match"], "operationId": "getTinMatch", "summary": "Read a TIN match result",
        "security": [ { "bearerAuth": ["filings:read"] } ],
        "parameters": [ { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "The match result when ready." } } }
    },
    "/v1/orders": {
      "get": { "tags": ["Orders"], "operationId": "listOrders", "summary": "List paid orders",
        "security": [ { "bearerAuth": ["payments:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ],
        "responses": { "200": { "description": "A page of orders." } } }
    },
    "/v1/orders/{id}": {
      "get": { "tags": ["Orders"], "operationId": "getOrder", "summary": "Read an order",
        "security": [ { "bearerAuth": ["payments:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "The order." }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/v1/orders/{id}/copy-b": {
      "get": { "tags": ["Documents"], "operationId": "getOrderCopyB", "summary": "Copy B bundle for an order (PDF)",
        "security": [ { "bearerAuth": ["payments:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "The Copy B bundle.", "content": { "application/pdf": {} } } } }
    },
    "/v1/webhooks": {
      "get": { "tags": ["Webhooks"], "operationId": "listWebhooks", "summary": "List webhook endpoints",
        "security": [ { "bearerAuth": ["webhooks:read"] } ],
        "responses": { "200": { "description": "The registered endpoints." } } },
      "post": { "tags": ["Webhooks"], "operationId": "createWebhook", "summary": "Register a webhook endpoint",
        "security": [ { "bearerAuth": ["webhooks:write"] } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } },
        "responses": { "201": { "description": "The endpoint and its signing secret (shown once)." } } }
    },
    "/v1/webhooks/{id}": {
      "patch": { "tags": ["Webhooks"], "operationId": "updateWebhook", "summary": "Update a webhook endpoint",
        "security": [ { "bearerAuth": ["webhooks:write"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } },
        "responses": { "200": { "description": "The updated endpoint." } } },
      "delete": { "tags": ["Webhooks"], "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint",
        "security": [ { "bearerAuth": ["webhooks:write"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "204": { "description": "Deleted." } } }
    },
    "/v1/webhooks/{id}/rotate-secret": {
      "post": { "tags": ["Webhooks"], "operationId": "rotateWebhookSecret", "summary": "Rotate a webhook signing secret",
        "security": [ { "bearerAuth": ["webhooks:write"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "The new signing secret (shown once)." } } }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": { "tags": ["Webhooks"], "operationId": "listWebhookDeliveries", "summary": "Webhook delivery history",
        "security": [ { "bearerAuth": ["webhooks:read"] } ],
        "parameters": [ { "$ref": "#/components/parameters/Id" } ],
        "responses": { "200": { "description": "Recent deliveries and their status." } } }
    },
    "/v1/sandbox/reset": {
      "post": { "tags": ["Sandbox"], "operationId": "resetSandbox", "summary": "Reset the sandbox company",
        "description": "Sandbox only. Clears filings, carts and orders back to a clean deterministic state.",
        "security": [ { "bearerAuth": ["filings:write"] } ],
        "responses": { "200": { "description": "Sandbox reset." } } }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http", "scheme": "bearer",
        "description": "An API key (`sk_live_…` / `sk_sandbox_…`) or an OAuth access token in the `Authorization: Bearer` header. The `sk_` prefix routes the request to the matching world."
      },
      "oauth2": {
        "type": "oauth2",
        "flows": { "clientCredentials": {
          "tokenUrl": "https://api.e1099f.com/oauth/token",
          "scopes": {
            "filings:read": "Read payers, recipients, forms and filings",
            "filings:write": "Create and correct filings",
            "payments:read": "Read balance and orders",
            "payments:write": "Add funds and pay the cart",
            "webhooks:read": "Read webhook endpoints and deliveries",
            "webhooks:write": "Manage webhook endpoints"
          } } }
      }
    },
    "parameters": {
      "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
      "PayerId": { "name": "payerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The payer every form in the call is published under." },
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Claimed before work starts; a racing retry gets 409 instead of double-filing." },
      "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500 } },
      "StartingAfter": { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: the id of the last item on the previous page." }
    },
    "schemas": {
      "Service": {
        "type": "string",
        "enum": ["efile", "efile_print_mail", "print_mail"],
        "description": "`efile` = e-file to the IRS; `efile_print_mail` = e-file + printed & mailed paper copy + recipient portal access (the default); `print_mail` = paper only. Recipient portal access is mandatory on any e-file service."
      },
      "USAddress": {
        "type": "object", "required": ["AddressLine1Txt", "CityNm", "StateAbbreviationCd", "ZIPCd"],
        "properties": {
          "AddressLine1Txt": { "type": "string" }, "AddressLine2Txt": { "type": "string" },
          "CityNm": { "type": "string" }, "StateAbbreviationCd": { "type": "string" }, "ZIPCd": { "type": "string" } }
      },
      "PayerFormsIntake": {
        "type": "object", "required": ["forms"],
        "properties": {
          "reference": { "type": "string", "description": "Your id, echoed back on each row." },
          "addToCart": { "type": "boolean", "description": "Stage the saved forms in the cart." },
          "service": { "$ref": "#/components/schemas/Service" },
          "forms": { "type": "array", "items": {
            "type": "object", "required": ["form", "tax_year", "jsonForm"],
            "properties": {
              "form": { "type": "string", "example": "1099-NEC" },
              "tax_year": { "type": "integer", "example": 2025 },
              "jsonForm": { "type": "object", "description": "The filled scheme from GET /v1/forms/{form}: RecipientDetail plus element values." } } } }
        }
      },
      "PayerFormsIntakeResult": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "example": "payer_forms_intake" },
          "payer": { "type": "string", "format": "uuid" },
          "created": { "type": "integer" }, "failed": { "type": "integer" }, "livemode": { "type": "boolean" },
          "forms": { "type": "array", "items": {
            "type": "object", "properties": {
              "reference": { "type": "string" }, "id": { "type": ["string", "null"], "format": "uuid" },
              "status": { "type": "string", "enum": ["ready_to_file", "in_cart", "failed"] },
              "added_to_cart": { "type": "boolean" }, "cart_item_id": { "type": ["string", "null"] },
              "service": { "$ref": "#/components/schemas/Service" },
              "error": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "FireImportResult": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "example": "fire_file" },
          "bytes": { "type": "integer" }, "rows_parsed": { "type": "integer" },
          "forms_imported": { "type": "integer" }, "forms_added_to_cart": { "type": "integer" },
          "form_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } },
          "currency": { "type": "string", "example": "usd" },
          "notes": { "type": "array", "items": { "type": "string" } }
        }
      },
      "PayerInput": {
        "type": "object", "required": ["name", "tin"],
        "properties": {
          "name": { "type": "string" }, "tin": { "type": "string" }, "tin_type": { "type": "string", "enum": ["ein", "ssn"] },
          "address_line1": { "type": "string" }, "address_line2": { "type": "string" },
          "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" } }
      },
      "RecipientInput": {
        "type": "object", "required": ["name", "tin"],
        "properties": {
          "name": { "type": "string" }, "tin": { "type": "string" }, "tin_type": { "type": "string", "enum": ["ein", "ssn"] },
          "address_line1": { "type": "string" }, "address_line2": { "type": "string" },
          "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" } }
      },
      "WebhookInput": {
        "type": "object", "required": ["url", "events"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "events": { "type": "array", "items": { "type": "string", "enum": ["filing.accepted", "filing.rejected", "tin_match.completed", "cart.paid"] } },
          "environment": { "type": "string", "enum": ["sandbox", "production"] } }
      },
      "Error": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "example": "invalid_request" },
          "message": { "type": "string" }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "properties": { "error": { "$ref": "#/components/schemas/Error" } }
      }
    },
    "responses": {
      "InvalidRequest": { "description": "Malformed or missing parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
      "Unauthorized": { "description": "Missing, invalid or expired credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
      "Forbidden": { "description": "The token's scopes or the app's payer authorization don't cover this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
      "NotFound": { "description": "No such resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
      "InProgress": { "description": "An identical request is already in flight (idempotency).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
      "Payer": { "description": "A payer.", "content": { "application/json": { "schema": { "type": "object" } } } },
      "PayerList": { "description": "A page of payers.", "content": { "application/json": { "schema": { "type": "object" } } } }
    }
  }
}