{
  "openapi": "3.1.0",
  "info": {
    "title": "ModernTax Partner API",
    "version": "1.0.0",
    "summary": "Order IRS tax transcripts under a signed Form 8821 and read them back as documents and structured data.",
    "description": "REST API for lenders and lending platforms. Each API key belongs to one organisation; every route only sees that organisation's orders, and another organisation's ids read as not found.\n\n**Flow.** (1) `POST /api/intake/transcript` with a `request_token` you choose (your idempotency key) and one or more taxpayers. Attach the taxpayer-signed Form 8821 naming ModernTax as designee inline (`signed_8821.pdf_base64`) or afterwards with `POST /api/intake/8821-pdf`. Orders without an 8821 are accepted but wait in `submitted` (`awaiting_authorization`) and are not worked. (2) Poll `GET /api/intake/transcript?token=<request_token>` until `status` is `completed`. (3) Read parsed data with `GET /api/v1/transcripts/{entityId}/structured` or compare borrower figures with `POST /api/v1/transcripts/{entityId}/cross-reference`.\n\n**Fiscal year end.** `fiscal_year_end_month` (1-12, 12 = calendar year) is required for Forms 1120, 1120S and 1065, including an EIN order with no `form_type` (EIN orders default to 1120). Missing it is a 400.\n\n**Sandbox.** Use `https://staging.portal.moderntax.io` with a staging key: synthetic data, simulated IRS keyed by the last four digits of the TIN (`0001` clean, `0002` tax lien, `0003` balance due, `0004` latest year unfiled, `0005` wrong form, `0006`-`0008` IRS errors), nothing billed or sent to the IRS. On staging the signed-8821 acceptance rules are enforced (422 on a rejected 8821); in production they are off unless enabled. Keys are per environment: a staging key does not work on production and vice versa.\n\n**Webhooks.** There is no per-request callback URL. If ModernTax has configured a webhook URL for your account, API orders also push JSON POSTs to it keyed by `request_token` (`status` `partial` | `complete` | `error`). When a webhook secret is set, each delivery carries `X-ModernTax-Signature`: hex HMAC-SHA256 of the raw body. Failed deliveries (5xx, timeout) retry up to 5 attempts; 400/404 responses are not retried. Polling is always available.\n\n**MCP.** The same API is exposed as Model Context Protocol tools at `/api/mcp` (stateless streamable HTTP, JSON-RPC over POST; `Authorization: Bearer <key>` or `x-api-key`). A self-serve sandbox key from `POST /api/sandbox/signup` gets the read-only tools in production (no `order_transcripts`); live keys need MCP enabled for the account. Staging keys get every tool against the simulated IRS. See `x-mcp`.\n\nFeature-gated routes (Tie-Out, QoE, Portfolio) return 404 or 403 until enabled for your account; they are on for everyone on staging.",
    "contact": {
      "name": "ModernTax API",
      "email": "matt@moderntax.io"
    },
    "x-security-contact": "security@moderntax.io",
    "license": {
      "name": "Proprietary",
      "url": "https://moderntax.io/terms.html"
    }
  },
  "externalDocs": {
    "description": "ModernTax API documentation",
    "url": "https://moderntax.io/docs"
  },
  "servers": [
    {
      "url": "https://portal.moderntax.io",
      "description": "Production"
    },
    {
      "url": "https://staging.portal.moderntax.io",
      "description": "Staging / sandbox (synthetic data, simulated IRS, nothing billed)"
    }
  ],
  "x-mcp": {
    "url": "https://portal.moderntax.io/api/mcp",
    "transport": "streamable-http",
    "auth": "same API key",
    "staging_url": "https://staging.portal.moderntax.io/api/mcp",
    "tools": [
      "verify_entity",
      "order_transcripts",
      "get_order_status",
      "get_transcript_data",
      "cross_reference"
    ]
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Transcripts",
      "description": "Place transcript orders and poll results."
    },
    {
      "name": "Authorization",
      "description": "Attach the taxpayer-signed Form 8821 to an order."
    },
    {
      "name": "Monitoring",
      "description": "Recurring transcript re-pulls."
    },
    {
      "name": "Data",
      "description": "Structured transcript data and checks."
    },
    {
      "name": "Employment",
      "description": "Employment / income verification (VOE / VOI) from IRS Wage & Income transcripts. Must be enabled for your account."
    },
    {
      "name": "Portfolio",
      "description": "Per-business portfolio profiles. Must be enabled for your account."
    },
    {
      "name": "Tie-Out",
      "description": "Filed return vs IRS transcript, line by line. Feature-gated."
    },
    {
      "name": "QoE",
      "description": "Quality-of-earnings workpapers. Feature-gated."
    },
    {
      "name": "Sandbox",
      "description": "Self-serve sandbox keys and staging-only test helpers."
    }
  ],
  "paths": {
    "/api/intake/transcript": {
      "post": {
        "tags": [
          "Transcripts"
        ],
        "operationId": "createTranscriptOrder",
        "summary": "Order IRS transcripts",
        "description": "Creates one order with one or more taxpayers. Billable (except on sandbox accounts). Entities with a signed 8821 go to `irs_queue`; entities without one wait in `submitted` until you attach it. Before queueing, ModernTax checks for transcripts already on file for the same TIN and may deliver them immediately (`served_from_record`). Body limit 64 MB. Signed-8821 acceptance rules are enforced on staging (422, nothing created).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranscriptOrderRequest"
              },
              "examples": {
                "sandbox": {
                  "summary": "Sandbox order (staging test TIN, clean scenario)",
                  "value": {
                    "request_token": "test-001",
                    "loan_number": "LN-001",
                    "entities": [
                      {
                        "entity_name": "Sandbox Coffee LLC",
                        "tid": "00-1230001",
                        "tid_kind": "EIN",
                        "form_type": "1120S",
                        "years": [
                          "2023",
                          "2024"
                        ],
                        "fiscal_year_end_month": 12,
                        "signed_8821": {
                          "pdf_base64": "<base64 PDF>",
                          "signer_name": "Jordan Example",
                          "signer_email": "jordan@example.com",
                          "signed_at": "2026-10-26T17:55:00Z",
                          "signature_vendor": "docusign"
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranscriptOrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, missing/invalid fields (`details` lists each), missing fiscal_year_end_month, form/TIN-kind mismatch, or an unorderable year (`error: \"Unorderable tax year requested\"`, `blocked[]`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Account cannot place paid orders yet (the status can also be another 4xx set by the gate).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderGateError"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate request_token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "existing_request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request body too large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "A signed 8821 failed the acceptance rules (staging, or production when enforcement is enabled). Nothing was created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "const": "Signed 8821 rejected"
                    },
                    "entities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "entity_name": {
                            "type": "string"
                          },
                          "failed_rules": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/SignatureRuleResult"
                            }
                          },
                          "signature_check": {
                            "$ref": "#/components/schemas/SignatureCheck"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Monthly API request limit reached (counted per calendar month, UTC).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "period": {
                          "type": "string",
                          "description": "YYYY-MM"
                        },
                        "resets_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds until the monthly window resets."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds."
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "details": {
                      "type": "string"
                    },
                    "retryable": {
                      "type": "boolean",
                      "description": "Present on entity-creation failure: true means the same request_token can be retried."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Transcripts"
        ],
        "operationId": "getTranscriptOrder",
        "summary": "Poll an order for status and results",
        "description": "Returns order status and, as transcripts land, signed download URLs (valid 1 hour) and parsed compliance data. Poll on your own cadence. On staging each poll also advances the simulated IRS.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "The request_token you used when ordering.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "schema",
            "in": "query",
            "required": false,
            "description": "Response shape. Omit for your account default (if pinned) or the default shape.",
            "schema": {
              "type": "string",
              "enum": [
                "minimal",
                "underwriting",
                "raw"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order status and results.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TranscriptResultDefault"
                    },
                    {
                      "$ref": "#/components/schemas/TranscriptResultShaped"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "token missing, or invalid schema value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No order with that token under your account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/intake/8821-pdf": {
      "post": {
        "tags": [
          "Authorization"
        ],
        "operationId": "uploadSigned8821Pdf",
        "summary": "Attach a signed 8821 PDF to an existing order",
        "description": "Attaches the taxpayer-signed Form 8821 to one entity of an order and moves it from pending/submitted/8821_sent to `8821_signed` so it can be worked. The PDF must name a ModernTax designee; a form naming another designee's CAF is rejected (422) and not attached. PDFs with no readable CAF are accepted.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "request_token"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Signed 8821 PDF, max 10 MB."
                  },
                  "request_token": {
                    "type": "string"
                  },
                  "entity_name": {
                    "type": "string",
                    "description": "Required unless entity_id is given. Case-insensitive match within the order."
                  },
                  "entity_id": {
                    "type": "string",
                    "description": "Takes precedence over entity_name.",
                    "format": "uuid"
                  },
                  "years": {
                    "type": "string",
                    "description": "Optional replacement years: \"2022,2023,2024\" or \"2022-2024\" (1990 to 2028)."
                  },
                  "form_type": {
                    "type": "string",
                    "description": "Optional form type override."
                  },
                  "signer_name": {
                    "type": "string",
                    "description": "Human signer, never a business name."
                  },
                  "signer_email": {
                    "type": "string"
                  },
                  "signed_at": {
                    "type": "string",
                    "description": "ISO 8601.",
                    "format": "date-time"
                  },
                  "signature_vendor": {
                    "type": "string"
                  },
                  "persona_inquiry_id": {
                    "type": "string"
                  },
                  "persona_verification_token": {
                    "type": "string"
                  },
                  "signer_ip": {
                    "type": "string",
                    "description": "Stored internally, never returned."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Attached.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "entity",
                    "designee_check",
                    "signature_evidence_stored"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "entity": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "signed_8821_url": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Signed URL (1 hour)."
                        },
                        "years": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "form_type": {
                          "type": "string"
                        }
                      }
                    },
                    "designee_check": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "unreadable"
                      ]
                    },
                    "signature_evidence_stored": {
                      "type": "boolean"
                    },
                    "signature_check": {
                      "$ref": "#/components/schemas/SignatureCheck"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Not multipart, missing file/request_token/entity, not a PDF, too large, invalid years, invalid signed_at, or form/TIN-kind mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "request_token not found for your account, or entity not found in the order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Several entities share that name; pass entity_id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "entity_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Designee CAF is not ModernTax's, or the signature rules rejected the 8821. Not attached.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "designee_caf_mismatch",
                        "signature_rules_failed"
                      ]
                    },
                    "designee_cafs": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "failed_rules": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SignatureRuleResult"
                      }
                    },
                    "signature_check": {
                      "$ref": "#/components/schemas/SignatureCheck"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/intake/8821": {
      "post": {
        "tags": [
          "Authorization"
        ],
        "operationId": "recordSigned8821Metadata",
        "summary": "Record signed-8821 details for entities (CSV/XLSX or JSON)",
        "description": "Metadata only: no PDF is uploaded here (use POST /api/intake/8821-pdf or inline signed_8821 to send the form). Matches rows to entities by request_token plus entity_id or entity_name, stores signer details, and advances entities in pending/submitted/8821_sent to `irs_queue`. Max 500 rows. Returns 422 when no row was applied.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "entities"
                ],
                "properties": {
                  "entities": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "request_token"
                      ],
                      "properties": {
                        "request_token": {
                          "type": "string"
                        },
                        "entity_id": {
                          "type": "string"
                        },
                        "entity_name": {
                          "type": "string"
                        },
                        "signer_first_name": {
                          "type": "string"
                        },
                        "signer_last_name": {
                          "type": "string"
                        },
                        "signer_email": {
                          "type": "string"
                        },
                        "signature_date": {
                          "type": "string",
                          "description": "ISO 8601 date, or an Excel date serial in CSV/XLSX."
                        }
                      }
                    },
                    "minItems": 1,
                    "description": "Each entry needs request_token and entity_id or entity_name."
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "CSV or XLSX; first sheet is read. Columns as in the JSON rows (common header variants accepted)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "At least one row applied; inspect results.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "partial",
                    "summary",
                    "results"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "true only when every row applied."
                    },
                    "partial": {
                      "type": "boolean"
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "rows_processed": {
                          "type": "integer"
                        },
                        "updated": {
                          "type": "integer"
                        },
                        "not_found": {
                          "type": "integer"
                        },
                        "errors": {
                          "type": "integer"
                        },
                        "no_change": {
                          "type": "integer"
                        }
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "row": {
                            "type": "integer"
                          },
                          "request_token": {
                            "type": "string"
                          },
                          "entity_name": {
                            "type": "string"
                          },
                          "entity_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "updated",
                              "not_found",
                              "error",
                              "no_change"
                            ]
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing entities/file, empty file, unsupported Content-Type, or row validation errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "More than 500 rows.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "rows_received": {
                      "type": "integer"
                    },
                    "max_rows": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "No row was applied.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "partial",
                    "summary",
                    "results"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "true only when every row applied."
                    },
                    "partial": {
                      "type": "boolean"
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "rows_processed": {
                          "type": "integer"
                        },
                        "updated": {
                          "type": "integer"
                        },
                        "not_found": {
                          "type": "integer"
                        },
                        "errors": {
                          "type": "integer"
                        },
                        "no_change": {
                          "type": "integer"
                        }
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "row": {
                            "type": "integer"
                          },
                          "request_token": {
                            "type": "string"
                          },
                          "entity_name": {
                            "type": "string"
                          },
                          "entity_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "updated",
                              "not_found",
                              "error",
                              "no_change"
                            ]
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/intake/monitoring": {
      "post": {
        "tags": [
          "Monitoring"
        ],
        "operationId": "enrollMonitoring",
        "summary": "Enroll an entity in recurring transcript monitoring",
        "description": "Creates a billable monitoring subscription for one entity of an existing order (your API call is recorded as the opt-in). Unless skip_initial_pull is true, an initial pull is queued immediately and its outcome is reported in `immediate_pull_status`. One active subscription per entity and per taxpayer under your account (409 otherwise). Monitoring re-pulls are not simulated on staging.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "request_token",
                  "frequency"
                ],
                "properties": {
                  "request_token": {
                    "type": "string"
                  },
                  "entity_name": {
                    "type": "string",
                    "description": "Required unless entity_id is given."
                  },
                  "entity_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "weekly",
                      "monthly",
                      "quarterly",
                      "annual",
                      "custom"
                    ]
                  },
                  "custom_interval_days": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Required when frequency is custom."
                  },
                  "skip_initial_pull": {
                    "type": "boolean",
                    "default": false
                  },
                  "expires_at": {
                    "type": "string",
                    "description": "Auto-cancel after this date.",
                    "format": "date"
                  },
                  "next_pull_date": {
                    "type": "string",
                    "description": "Overrides the computed next pull date.",
                    "format": "date"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "subscription",
                    "immediate_pull_status",
                    "skipped_initial_pull"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "subscription": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "entity_id": {
                          "type": "string"
                        },
                        "entity_name": {
                          "type": "string"
                        },
                        "frequency": {
                          "type": "string"
                        },
                        "custom_interval_days": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "next_pull_date": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string"
                        }
                      }
                    },
                    "immediate_pull": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "assignment_id": {
                          "type": "string"
                        },
                        "sla_deadline": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "const": "expert_assigned"
                        }
                      }
                    },
                    "immediate_pull_status": {
                      "type": "string",
                      "enum": [
                        "skipped_by_request",
                        "assigned",
                        "no_experts_available",
                        "assignment_failed"
                      ],
                      "description": "Only `assigned` means a pull is queued today; otherwise the scheduler picks it up on next_pull_date."
                    },
                    "skipped_initial_pull": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, missing request_token/entity, invalid frequency, or custom without custom_interval_days.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "request_token or entity not found under your account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Already monitored (entity or taxpayer), or several entities share that name.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "subscription": {
                      "type": "object"
                    },
                    "entity_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/transcripts/{entityId}/structured": {
      "get": {
        "tags": [
          "Data"
        ],
        "operationId": "getStructuredTranscripts",
        "summary": "Structured transcript data for one entity",
        "description": "Parses every HTML transcript on file for the entity into filings (financials, transaction codes, flags) plus a compliance synthesis and `tax_compliance`. Returns what is on file now; empty arrays while the order is pending.",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "description": "ModernTax entity id (`entity_id` / `entities[].entity_id` from the order response). Must belong to an order placed under your API key; any other id reads as not found.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "entity",
                    "filings",
                    "compliance",
                    "tax_compliance",
                    "transcripts_parsed_count"
                  ],
                  "properties": {
                    "entity": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "tin": {
                          "type": "string"
                        },
                        "tid_kind": {
                          "type": "string"
                        },
                        "form_type": {
                          "type": "string"
                        },
                        "years": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "fiscal_year_end_month": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string"
                        },
                        "completed_at": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "loan_number": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "filings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "form": {
                            "type": "string"
                          },
                          "period": {
                            "type": "string",
                            "description": "Tax year, or \"unknown\"."
                          },
                          "tax_period_ending": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "MM-DD-YYYY as printed."
                          },
                          "filed_on": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Date of TC 150, when present."
                          },
                          "transcript_source": {
                            "type": "string"
                          },
                          "financials": {
                            "type": "object",
                            "properties": {
                              "gross_receipts": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_income": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_deductions": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_tax": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "agi": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "account_balance": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "accrued_interest": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "accrued_penalty": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "account_balance_plus_accruals": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            }
                          },
                          "transaction_codes": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "code": {
                                  "type": "string"
                                },
                                "explanation": {
                                  "type": "string"
                                },
                                "date": {
                                  "type": "string"
                                },
                                "amount": {}
                              }
                            }
                          },
                          "severity": {
                            "type": "string"
                          },
                          "flags": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/ComplianceFlag"
                            }
                          },
                          "is_blank_or_unfiled": {
                            "type": "boolean"
                          }
                        }
                      },
                      "description": "Newest period first."
                    },
                    "compliance": {
                      "type": "object",
                      "properties": {
                        "overall_severity": {
                          "type": "string"
                        },
                        "headline_summary": {
                          "type": "string"
                        },
                        "filing_compliance": {
                          "type": "object",
                          "properties": {
                            "filed": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            },
                            "unfiled": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          }
                        },
                        "tax_liabilities": {
                          "type": "object",
                          "properties": {
                            "rows": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            },
                            "total_assessed": {
                              "type": "number"
                            },
                            "total_paid": {
                              "type": "number"
                            },
                            "total_balance": {
                              "type": "number"
                            },
                            "total_accrued": {
                              "type": "number"
                            }
                          }
                        },
                        "repayment_plan": {
                          "type": "object",
                          "properties": {
                            "has_installment_agreement": {
                              "type": "boolean"
                            },
                            "has_offer_in_compromise": {
                              "type": "boolean"
                            },
                            "has_currently_not_collectible": {
                              "type": "boolean"
                            },
                            "details": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "recommendation": {
                              "type": "string"
                            }
                          }
                        },
                        "estimated_payments": {},
                        "extensions_and_amendments": {}
                      }
                    },
                    "tax_compliance": {
                      "$ref": "#/components/schemas/TaxCompliance"
                    },
                    "income_baseline": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "income_snapshot": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "transcripts_parsed_count": {
                      "type": "integer"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "generated_at": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Entity not found under your account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/transcripts/{entityId}/cross-reference": {
      "post": {
        "tags": [
          "Data"
        ],
        "operationId": "crossReferenceFigures",
        "summary": "Compare borrower-reported figures with the IRS-filed return",
        "description": "Finds the transcript on file for tax_year and compares each submitted figure: MATCH within 1%, MINOR 1-5%, MATERIAL over 5%. Fields with no IRS value are listed in fields_not_comparable and never count as a match. Body limit 64 KB.",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "description": "ModernTax entity id (`entity_id` / `entities[].entity_id` from the order response). Must belong to an order placed under your API key; any other id reads as not found.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tax_year",
                  "self_reported"
                ],
                "properties": {
                  "tax_year": {
                    "type": "string",
                    "pattern": "^20\\d{2}$"
                  },
                  "self_reported": {
                    "type": "object",
                    "description": "At least one supported field. Non-numeric values are treated as missing.",
                    "properties": {
                      "gross_receipts": {
                        "type": "number"
                      },
                      "total_income": {
                        "type": "number"
                      },
                      "total_deductions": {
                        "type": "number"
                      },
                      "total_tax": {
                        "type": "number"
                      },
                      "agi": {
                        "type": "number"
                      }
                    }
                  }
                }
              },
              "example": {
                "tax_year": "2024",
                "self_reported": {
                  "gross_receipts": 1100000
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comparison. When no transcript exists for the year, `filed` is false, `diffs` is empty and only tax_year/filed/summary/diffs/overall_match are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "tax_year",
                    "filed",
                    "diffs",
                    "overall_match",
                    "summary"
                  ],
                  "properties": {
                    "tax_year": {
                      "type": "string"
                    },
                    "form": {
                      "type": "string"
                    },
                    "period_ending": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "filed": {
                      "type": "boolean"
                    },
                    "transcript_source": {
                      "type": "string"
                    },
                    "diffs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string"
                          },
                          "irs_filed": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "self_reported": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "delta_absolute": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "delta_pct": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "match": {
                            "type": "boolean"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "MATCH",
                              "MINOR",
                              "MATERIAL"
                            ]
                          }
                        }
                      }
                    },
                    "overall_match": {
                      "type": "boolean",
                      "description": "true only when at least one field was comparable and all comparable fields match."
                    },
                    "fields_not_comparable": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "summary": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, bad tax_year, or no supported self_reported field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Entity not found under your account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body too large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/broker-check": {
      "post": {
        "tags": [
          "Data"
        ],
        "operationId": "brokerCheck",
        "summary": "Broker lien / delinquency screen",
        "description": "Per-use screening product (each successful check is charged; `price_charged` in the response, $29.99 at time of writing). Checks the name against IRS records ModernTax already holds for the TIN and returns signals only: no transcript data, dollar amounts or names on file. Requires a billable account (payment gate) and counts toward your API request limit.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "tid"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Business or individual name."
                  },
                  "tid": {
                    "type": "string",
                    "description": "EIN or SSN, exactly 9 digits."
                  },
                  "tid_kind": {
                    "type": "string",
                    "enum": [
                      "EIN",
                      "SSN"
                    ],
                    "description": "Inferred from the format when omitted."
                  }
                }
              },
              "example": {
                "name": "Sandbox Coffee LLC",
                "tid": "00-1230001",
                "tid_kind": "EIN"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Check completed and charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrokerCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or validation errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Account cannot place paid orders yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderGateError"
                }
              }
            }
          },
          "413": {
            "description": "Request body too large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "API request limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Broker-check service not provisioned in this environment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/portfolio": {
      "get": {
        "tags": [
          "Portfolio"
        ],
        "operationId": "listPortfolio",
        "summary": "List portfolio businesses",
        "description": "Your businesses with portfolio filters. Requires the Portfolio product to be enabled for your account (403 otherwise).",
        "parameters": [
          {
            "name": "delegated",
            "in": "query",
            "required": false,
            "description": "1/true/yes or 0/false.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "acquisition",
            "in": "query",
            "required": false,
            "description": "1/true/yes or 0/false.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sold_secondary",
            "in": "query",
            "required": false,
            "description": "1/true/yes or 0/false.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "other_sba",
            "in": "query",
            "required": false,
            "description": "1/true/yes or 0/false.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "product",
            "in": "query",
            "required": false,
            "description": "Credit product, e.g. 7a, 504, sba_express, revolver.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Text search over name and NAICS.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Businesses.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "client",
                    "count",
                    "businesses"
                  ],
                  "properties": {
                    "client": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "businesses": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BusinessProfile"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Portfolio not enabled for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/portfolio/{entityId}": {
      "get": {
        "tags": [
          "Portfolio"
        ],
        "operationId": "getPortfolioBusiness",
        "summary": "One business profile",
        "description": "Builds the profile on first read. Requires the Portfolio product to be enabled for your account (403 otherwise).",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "description": "ModernTax entity id (`entity_id` / `entities[].entity_id` from the order response). Must belong to an order placed under your API key; any other id reads as not found.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "business"
                  ],
                  "properties": {
                    "business": {
                      "$ref": "#/components/schemas/BusinessProfile"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Portfolio not enabled for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Portfolio"
        ],
        "operationId": "refreshPortfolioSummary",
        "summary": "Regenerate the executive summary",
        "description": "Regenerates the business's executive summary. Requires the Portfolio product to be enabled for your account (403 otherwise).",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "description": "ModernTax entity id (`entity_id` / `entities[].entity_id` from the order response). Must belong to an order placed under your API key; any other id reads as not found.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "business"
                  ],
                  "properties": {
                    "business": {
                      "$ref": "#/components/schemas/BusinessProfile"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Portfolio not enabled for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Summary generation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tie-out": {
      "post": {
        "tags": [
          "Tie-Out"
        ],
        "operationId": "runTieOut",
        "summary": "Tie a filed return out to the IRS transcript",
        "description": "Compares the borrower's filed return (PDF) with the IRS transcript on file for the same form and year, line by line; variance = |return - IRS| > $1 and > 1% of the IRS figure, or a line on one side only. Supports 1120-S, 1065, 1120 and 1040 Schedule C. The result never certifies (`requires_review: true`). Keep the body under about 4 MB (platform limit); send larger returns through the portal. Feature-gated (`tie_out`): returns 404 `Not found` unless enabled for your account (on for all staging accounts).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "entity_id",
                  "tax_year",
                  "return_pdf_base64"
                ],
                "properties": {
                  "entity_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "tax_year": {
                    "type": "string",
                    "pattern": "^20\\d{2}$"
                  },
                  "return_pdf_base64": {
                    "type": "string",
                    "description": "Base64 PDF (a data:application/pdf;base64, prefix is stripped)."
                  },
                  "filename": {
                    "type": "string"
                  },
                  "form": {
                    "type": "string",
                    "description": "Defaults to the entity's form. Accepts 1120S, 1065, 1120, 1040 (Schedule C)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tie-out run.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "run"
                  ],
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/TieOutRun"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing fields, bad tax_year, unsupported form, or not a PDF.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Feature off for your account, or entity not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body too large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Return reader unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tie-out/{entityId}": {
      "get": {
        "tags": [
          "Tie-Out"
        ],
        "operationId": "getTieOutRuns",
        "summary": "Stored Tie-Out results or workpapers",
        "description": "JSON runs, or a file when `artifact` is given. Feature-gated (`tie_out`): returns 404 `Not found` unless enabled for your account (on for all staging accounts).",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "description": "ModernTax entity id (`entity_id` / `entities[].entity_id` from the order response). Must belong to an order placed under your API key; any other id reads as not found.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "tax_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}$"
            }
          },
          {
            "name": "artifact",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "workpaper_pdf",
                "workpaper_xlsx",
                "data_pack"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON runs, or the requested file.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "entity_id",
                    "runs"
                  ],
                  "properties": {
                    "entity_id": {
                      "type": "string"
                    },
                    "runs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TieOutRun"
                      }
                    }
                  }
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid artifact.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Feature off, entity not found, or no tie-out run yet (for workpapers).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/qoe/{entityId}": {
      "get": {
        "tags": [
          "QoE"
        ],
        "operationId": "getQoeWorkpapers",
        "summary": "Quality-of-earnings workpapers (read-only)",
        "description": "JSON workpapers (schema `moderntax.qoe.v1`: status DRAFT/FINAL with blockers and sign-off, engagement, periods, sources and coverage, four_way, proof_of_cash, adjustments, sustainability, summary, open_items, audit), or a file when `artifact` is given. A DRAFT is not for reliance. Data goes in through the portal. Feature-gated (`proof_of_cash`): returns 404 `Not found` unless enabled for your account (on for all staging accounts).",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "description": "ModernTax entity id (`entity_id` / `entities[].entity_id` from the order response). Must belong to an order placed under your API key; any other id reads as not found.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "artifact",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "qoe_xlsx",
                "qoe_pdf",
                "qoe_json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Workpapers JSON, or the requested file.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "entity_id",
                    "qoe"
                  ],
                  "properties": {
                    "entity_id": {
                      "type": "string"
                    },
                    "qoe": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "type": "string",
                          "const": "moderntax.qoe.v1"
                        },
                        "generated_at": {
                          "type": "string"
                        },
                        "status": {
                          "type": "object",
                          "properties": {
                            "report_status": {
                              "type": "string",
                              "enum": [
                                "DRAFT",
                                "FINAL"
                              ]
                            },
                            "stamp": {
                              "type": "string"
                            },
                            "can_finalize": {
                              "type": "boolean"
                            },
                            "blockers": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "signoff": {}
                          }
                        }
                      },
                      "additionalProperties": true
                    }
                  }
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid artifact.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Feature off for your account, or entity not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook/employment-intake": {
      "post": {
        "tags": [
          "Employment"
        ],
        "operationId": "createEmploymentOrder",
        "summary": "Order an employment / income verification",
        "description": "Creates a VOE (employment) or VOI (employment + income) order for one individual from IRS Wage & Income transcripts. Requires employment verification to be enabled for your account (403 `employment_not_enabled` otherwise). The SSN is never echoed back.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "request_token",
                  "employee_name",
                  "employee_ssn",
                  "years"
                ],
                "properties": {
                  "request_token": {
                    "type": "string",
                    "description": "Your unique id (idempotency key)."
                  },
                  "employee_name": {
                    "type": "string"
                  },
                  "employee_ssn": {
                    "type": "string",
                    "description": "9 digits, dashes optional."
                  },
                  "employee_address": {
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": "string"
                      },
                      "city": {
                        "type": "string"
                      },
                      "state": {
                        "type": "string"
                      },
                      "zip": {
                        "type": "string"
                      }
                    }
                  },
                  "years": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1
                  },
                  "report_type": {
                    "type": "string",
                    "enum": [
                      "voe",
                      "voi"
                    ],
                    "default": "voi"
                  },
                  "requestor": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "organization": {
                        "type": "string",
                        "description": "Defaults to your organisation name."
                      },
                      "email": {
                        "type": "string"
                      },
                      "address": {
                        "type": "string"
                      },
                      "phone": {
                        "type": "string"
                      }
                    }
                  },
                  "permissible_purpose": {
                    "type": "string"
                  },
                  "tracking_number": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "request_token": "emp-test-001",
                "employee_name": "Jordan Example",
                "employee_ssn": "000-12-0001",
                "years": [
                  "2024"
                ],
                "report_type": "voi"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "request_id",
                    "request_token",
                    "report_type",
                    "usage"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "entity_id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "request_token": {
                      "type": "string"
                    },
                    "report_type": {
                      "type": "string",
                      "enum": [
                        "voe",
                        "voi"
                      ]
                    },
                    "usage": {
                      "$ref": "#/components/schemas/Usage"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing required field or invalid report_type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Employment verification not enabled (`code: employment_not_enabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate request_token. When the token is your own, the existing order is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "existing_request_id": {
                      "type": "string"
                    },
                    "request_token": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "idempotent_replay": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "API request limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook/employment-result": {
      "get": {
        "tags": [
          "Employment"
        ],
        "operationId": "getEmploymentResult",
        "summary": "Poll an employment verification",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "Your request_token.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pending or completed result.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "request_id",
                        "status"
                      ],
                      "properties": {
                        "request_id": {
                          "type": "string",
                          "description": "Echoes the token."
                        },
                        "status": {
                          "type": "string",
                          "const": "pending_irs_call"
                        },
                        "request_status": {
                          "type": "string"
                        },
                        "entity_status": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "employment": {
                          "$ref": "#/components/schemas/EmploymentResult"
                        },
                        "employment_report": {
                          "type": "object",
                          "description": "Full VOE/VOI report object."
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "request_id",
                        "status",
                        "result"
                      ],
                      "properties": {
                        "request_id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "const": "completed"
                        },
                        "result": {
                          "type": "object",
                          "description": "Parsed employment data."
                        },
                        "employment": {
                          "$ref": "#/components/schemas/EmploymentResult"
                        },
                        "employment_report": {
                          "type": "object"
                        },
                        "transcript_urls": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Signed URLs (1 hour)."
                        },
                        "completed_at": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "token missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No order with that token under your account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook/employment-result/pdf": {
      "get": {
        "tags": [
          "Employment"
        ],
        "operationId": "getEmploymentReportPdf",
        "summary": "Employment report as PDF",
        "description": "While the order is pending the PDF says so; it never shows unverified data.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file (Content-Disposition: attachment).",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "token missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No employment order with that token under your account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/sandbox/signup": {
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "createSandboxKey",
        "summary": "Self-serve sandbox API key",
        "security": [],
        "description": "Public, no auth. Creates a sandbox organisation (synthetic borrowers, free, billing-suppressed, request limit 250) and returns its API key once. One sandbox per business email domain (free-mail domains are rejected); an existing sandbox key is never re-shown or rotated here. The key works only on the server you called. The simulated IRS runs on staging only, so use staging for end-to-end order tests.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "company",
                  "email"
                ],
                "properties": {
                  "company": {
                    "type": "string",
                    "description": "2-80 characters."
                  },
                  "email": {
                    "type": "string",
                    "description": "Work email.",
                    "format": "email"
                  },
                  "website": {
                    "type": "string",
                    "description": "Honeypot. Leave empty; any value returns a fake success."
                  }
                }
              },
              "example": {
                "company": "Example Lending",
                "email": "dev@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A sandbox already exists for this email domain.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "already_exists",
                    "message"
                  ],
                  "properties": {
                    "already_exists": {
                      "type": "boolean",
                      "const": true
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Sandbox created (a honeypot hit also returns 201 with only `success`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "sandbox": {
                      "type": "string",
                      "description": "Sandbox slug."
                    },
                    "api_key": {
                      "type": "string",
                      "description": "Shown once. Store it now."
                    },
                    "note": {
                      "type": "string"
                    },
                    "entities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          }
                        }
                      },
                      "description": "Synthetic entities you can read immediately."
                    },
                    "quickstart": {
                      "type": "string",
                      "description": "Example curl command."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, missing company, invalid or personal email.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Daily sandbox signup cap reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/sandbox/sample-8821": {
      "get": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "getSample8821",
        "summary": "Generate a dummy signed 8821 (staging only)",
        "servers": [
          {
            "url": "https://staging.portal.moderntax.io",
            "description": "Staging (sandbox). This route returns 404 on production."
          }
        ],
        "description": "Returns a synthetic signed 8821 (ModernTax template plus an e-signature completion certificate) ready to drop into `entities[].signed_8821`. `style` picks which acceptance rule it passes or breaks.",
        "parameters": [
          {
            "name": "entity_name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tid",
            "in": "query",
            "required": true,
            "description": "9 digits; use 00-XXXXXXX / 000-XX-XXXX test TINs.",
            "schema": {
              "type": "string"
            },
            "example": "00-1230001"
          },
          {
            "name": "form_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "1040",
                "1065",
                "1120",
                "1120S",
                "941"
              ]
            }
          },
          {
            "name": "years",
            "in": "query",
            "required": true,
            "description": "Comma list of 4-digit years.",
            "schema": {
              "type": "string"
            },
            "example": "2023,2024"
          },
          {
            "name": "tid_kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "EIN",
                "SSN"
              ]
            }
          },
          {
            "name": "signer_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "signer_title",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "signer_email",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "style",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "valid",
                "no_audit_trail",
                "wrong_designee",
                "signer_is_business",
                "wrong_tin",
                "stale"
              ],
              "default": "valid"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "pdf"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON (default) or the PDF (`format=pdf`, with X-Signer-Name, X-Signed-At, X-Signature-Vendor and X-Expect headers).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "style",
                    "expect",
                    "signed_8821"
                  ],
                  "properties": {
                    "style": {
                      "type": "string"
                    },
                    "expect": {
                      "type": "object",
                      "description": "Expected verdict and failed rule."
                    },
                    "signed_8821": {
                      "$ref": "#/components/schemas/Signed8821Inline"
                    }
                  }
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Validation errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not on staging.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/sandbox/advance": {
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "advanceSandboxOrder",
        "summary": "Finish a sandbox order now (staging only)",
        "servers": [
          {
            "url": "https://staging.portal.moderntax.io",
            "description": "Staging (sandbox). This route returns 404 on production."
          }
        ],
        "description": "Skips the simulated IRS wait (normally about 30 s to processing and 90 s to completed after the 8821 is attached). Entities without a signed 8821 PDF stay where they are.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "request_token"
                ],
                "properties": {
                  "request_token": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "request_token": "test-001"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Advanced.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "request_token",
                    "advanced"
                  ],
                  "properties": {
                    "request_token": {
                      "type": "string"
                    },
                    "advanced": {
                      "type": "integer"
                    },
                    "next": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "request_token missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing x-api-key header, or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not on staging, or order not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your ModernTax API key (one per organisation, per environment). The server looks the key up by its SHA-256 hash and compares in constant time. REST routes read only the `x-api-key` header; `Authorization: Bearer` is accepted by the MCP endpoint only. Rotating a key in the developer portal invalidates the old key immediately."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable message."
          },
          "details": {
            "description": "Validation messages (array) or an underlying error message (string).",
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "string"
              }
            ]
          },
          "code": {
            "type": "string",
            "description": "Machine-readable code, when the route sets one (e.g. `designee_caf_mismatch`, `signature_rules_failed`, `employment_not_enabled`)."
          }
        }
      },
      "OrderGateError": {
        "type": "object",
        "description": "Returned when the account cannot place paid orders yet (payment method, credits or deposit). Sandbox accounts always pass.",
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "Why ordering is blocked.",
            "examples": [
              "card_required",
              "credits_required",
              "mercury_required",
              "deposit_required"
            ]
          },
          "client_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "cta": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "href": {
                "type": "string"
              }
            }
          },
          "enroll_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_steps": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "completed_count": {
            "type": "integer"
          },
          "trial_remaining": {
            "type": "integer"
          },
          "has_recent_paid_invoice": {
            "type": "boolean"
          },
          "has_mercury_enrolled": {
            "type": "boolean"
          },
          "has_bypass": {
            "type": "boolean"
          },
          "is_sandbox": {
            "type": "boolean"
          }
        }
      },
      "Usage": {
        "type": "object",
        "required": [
          "used",
          "remaining",
          "limit"
        ],
        "properties": {
          "used": {
            "type": "integer"
          },
          "remaining": {
            "type": [
              "integer",
              "null"
            ],
            "description": "null when the account has no request limit."
          },
          "limit": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "SignatureRuleResult": {
        "type": "object",
        "required": [
          "id",
          "ok",
          "severity",
          "message"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Rule id: is_form_8821, taxpayer_tin_matches, designee_is_moderntax, esign_audit_trail, signer_named, signer_in_audit_trail, signed_at_valid, pdf_text_readable, signature_vendor_named."
          },
          "ok": {
            "type": "boolean"
          },
          "severity": {
            "type": "string",
            "enum": [
              "block",
              "warn"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SignatureCheck": {
        "type": "object",
        "description": "Signed-8821 acceptance check. Present only when signature rules are on (always on staging; off in production unless enabled).",
        "required": [
          "verdict",
          "audit_trail_vendor",
          "rules",
          "docs"
        ],
        "properties": {
          "verdict": {
            "type": "string",
            "enum": [
              "accepted",
              "rejected"
            ]
          },
          "audit_trail_vendor": {
            "type": [
              "string",
              "null"
            ],
            "description": "E-signature vendor whose completion certificate was recognised."
          },
          "rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignatureRuleResult"
            }
          },
          "docs": {
            "type": "string"
          }
        }
      },
      "Signed8821Inline": {
        "type": "object",
        "required": [
          "pdf_base64"
        ],
        "properties": {
          "pdf_base64": {
            "type": "string",
            "description": "Base64 of the signed 8821 PDF (max 10 MB decoded; must start with `%PDF-`). Include the e-signature vendor's audit trail / completion certificate as pages of the same PDF. Line 2 must name a ModernTax designee."
          },
          "signer_name": {
            "type": "string",
            "description": "Full name of the human who signed. Never a business name."
          },
          "signer_email": {
            "type": "string",
            "format": "email"
          },
          "signed_at": {
            "type": "string",
            "description": "ISO 8601 timestamp of the signature.",
            "format": "date-time"
          },
          "signature_vendor": {
            "type": "string",
            "description": "Free text, e.g. \"docusign\" or \"persona+dropbox_sign\"."
          },
          "persona_inquiry_id": {
            "type": "string"
          },
          "persona_verification_token": {
            "type": "string"
          },
          "signer_ip": {
            "type": "string",
            "description": "Stored internally, never returned."
          }
        }
      },
      "TranscriptEntityInput": {
        "type": "object",
        "required": [
          "entity_name",
          "tid",
          "years"
        ],
        "properties": {
          "entity_name": {
            "type": "string",
            "description": "Legal name of the taxpayer."
          },
          "tid": {
            "type": "string",
            "description": "EIN or SSN (9 digits, dashes optional)."
          },
          "tid_kind": {
            "type": "string",
            "enum": [
              "EIN",
              "SSN"
            ],
            "description": "Defaults to EIN."
          },
          "form_type": {
            "type": "string",
            "enum": [
              "1040",
              "1065",
              "1120",
              "1120S",
              "941"
            ],
            "description": "Defaults to 1120 for an EIN and 1040 for an SSN. 1040 requires an SSN; 1065/1120/1120S/941 require an EIN (mismatch is a 400)."
          },
          "years": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^\\d{4}$"
            },
            "description": "Tax years. Years that cannot be ordered (e.g. not yet closed) are rejected with 400, never silently dropped."
          },
          "fiscal_year_end_month": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12,
            "description": "Month the fiscal year ends; 12 = calendar year. REQUIRED for 1120, 1120S and 1065 (including an EIN order with no form_type). Ignored for 1040 and 941. The tax-year label is the calendar year the fiscal year ends in."
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip_code": {
            "type": "string"
          },
          "loan_officer_name": {
            "type": "string",
            "description": "Attribution. The top-level value wins if both are sent."
          },
          "loan_officer_email": {
            "type": "string"
          },
          "loan_amount": {
            "type": [
              "number",
              "string"
            ],
            "description": "Proposed loan amount in dollars (positive). Entity value wins over the top-level value."
          },
          "loan_purpose": {
            "type": "string",
            "description": "acquisition | refinance | working_capital | expansion | real_estate | equipment | other"
          },
          "signed_8821": {
            "$ref": "#/components/schemas/Signed8821Inline"
          }
        }
      },
      "TranscriptOrderRequest": {
        "type": "object",
        "required": [
          "request_token",
          "entities"
        ],
        "properties": {
          "request_token": {
            "type": "string",
            "description": "Your unique id for this order (idempotency key). Reusing a token returns 409."
          },
          "loan_number": {
            "type": "string",
            "description": "Defaults to request_token."
          },
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TranscriptEntityInput"
            },
            "minItems": 1
          },
          "notes": {
            "type": "string"
          },
          "loan_officer_name": {
            "type": "string"
          },
          "loan_officer_email": {
            "type": "string"
          },
          "loan_amount": {
            "type": [
              "number",
              "string"
            ]
          },
          "loan_purpose": {
            "type": "string"
          }
        }
      },
      "TranscriptOrderResponse": {
        "type": "object",
        "required": [
          "success",
          "request_id",
          "request_token",
          "status",
          "entities",
          "usage"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "request_id": {
            "type": "string",
            "description": "ModernTax request id.",
            "format": "uuid"
          },
          "request_token": {
            "type": "string"
          },
          "loan_number": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "awaiting_authorization",
              "irs_queue"
            ],
            "description": "`completed` when every entity was served from records already on file; `awaiting_authorization` when no entity has an 8821."
          },
          "awaiting_authorization": {
            "type": "object",
            "description": "Present only when some entities have no signed 8821 and will not be worked until one is attached.",
            "properties": {
              "count": {
                "type": "integer"
              },
              "entity_ids": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "message": {
                "type": "string"
              },
              "docs": {
                "type": "string"
              }
            }
          },
          "entities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "entity_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "entity_name": {
                  "type": "string"
                },
                "form_type": {
                  "type": "string"
                },
                "years": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "status": {
                  "type": "string",
                  "description": "`irs_queue` (8821 supplied), `submitted` (waiting for an 8821) or `completed` (served from record)."
                },
                "signed_8821": {
                  "type": "string",
                  "enum": [
                    "attached",
                    "unreadable_attached",
                    "rejected_designee_mismatch",
                    "attach_failed",
                    "identity_mismatch_not_attached"
                  ],
                  "description": "Present only when the entity carried signed_8821. Only `attached` and `unreadable_attached` mean the PDF is on file; otherwise retry with POST /api/intake/8821-pdf."
                },
                "signature_check": {
                  "$ref": "#/components/schemas/SignatureCheck"
                }
              }
            }
          },
          "served_from_record": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "entity_id": {
                  "type": "string"
                },
                "entity_name": {
                  "type": "string"
                },
                "prior_loan": {
                  "type": "string"
                },
                "transcripts": {
                  "type": "integer"
                }
              }
            },
            "description": "Entities delivered immediately from transcripts ModernTax already holds for the same TIN."
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "TaxCompliancePeriod": {
        "type": "object",
        "required": [
          "year",
          "period",
          "form_type",
          "filed",
          "status",
          "balance",
          "ordered"
        ],
        "properties": {
          "year": {
            "type": "string"
          },
          "period": {
            "type": "string",
            "description": "\"2024\" for annual returns, \"2024 Q3\" for 941."
          },
          "form_type": {
            "type": "string"
          },
          "filed": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "true = return on file; false = IRS shows no record of a required return; null = no determination."
          },
          "status": {
            "type": "string",
            "enum": [
              "filed",
              "unfiled",
              "filed_pending_posting",
              "not_required",
              "not_yet_due",
              "pending"
            ]
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "description": "IRS account balance plus accruals for the period; null when not determinable."
          },
          "ordered": {
            "type": "boolean",
            "description": "false = not part of the order (e.g. found on a discovery pull)."
          }
        }
      },
      "TaxCompliance": {
        "type": "object",
        "description": "Machine-readable filing and balance verdict built from the transcripts on file.",
        "required": [
          "filing_status",
          "last_filed_year",
          "balance_due",
          "balance_due_amount",
          "transcript_available",
          "as_of",
          "periods"
        ],
        "properties": {
          "filing_status": {
            "type": "string",
            "enum": [
              "current",
              "delinquent",
              "unfiled",
              "unknown"
            ],
            "description": "From answered periods only. A balance owed does not change filing_status."
          },
          "last_filed_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "balance_due": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "null when no Account Transcript / Record of Account is on file."
          },
          "balance_due_amount": {
            "type": [
              "number",
              "null"
            ]
          },
          "transcript_available": {
            "type": "boolean"
          },
          "as_of": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "periods": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxCompliancePeriod"
            }
          }
        }
      },
      "ComplianceFlag": {
        "type": "object",
        "required": [
          "type",
          "severity",
          "message"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "description": "CRITICAL | WARNING | INFO-style severity as screened."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "QoeQualification": {
        "type": [
          "object",
          "null"
        ],
        "description": "QoE qualification screen for the loan stated at intake. Present only when the qoe_screen feature is enabled for your account; null when no loan or result exists.",
        "properties": {
          "loan_amount": {
            "type": [
              "number",
              "null"
            ]
          },
          "loan_purpose": {
            "type": [
              "string",
              "null"
            ]
          },
          "verdict": {
            "type": [
              "string",
              "null"
            ]
          },
          "recommended": {
            "description": "As produced by the screen."
          },
          "headline": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_steps": {
            "type": "array",
            "items": {}
          },
          "checks": {
            "type": "array",
            "items": {}
          },
          "dscr_proxy": {},
          "fee_estimate": {},
          "checked_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SandboxInfo": {
        "type": "object",
        "description": "Staging only.",
        "required": [
          "scenario"
        ],
        "properties": {
          "scenario": {
            "type": "string",
            "description": "Simulated IRS scenario chosen by the TIN's last four digits."
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "fix": {
                "type": "string"
              },
              "billable": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "TranscriptResultEntity": {
        "type": "object",
        "properties": {
          "entity_id": {
            "type": "string",
            "format": "uuid"
          },
          "entity_name": {
            "type": "string"
          },
          "tid": {
            "type": "string",
            "description": "Taxpayer TIN as stored (formatted)."
          },
          "tid_kind": {
            "type": "string"
          },
          "form_type": {
            "type": "string"
          },
          "years": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string",
            "description": "Entity status, e.g. submitted, irs_queue, 8821_signed, processing, completed, failed, cancelled."
          },
          "signed_8821_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Signed URL (1 hour) of the 8821 on file."
          },
          "signature_created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "signature_evidence": {
            "type": [
              "object",
              "null"
            ],
            "description": "Partner-attested signature evidence as supplied (signer_ip removed)."
          },
          "transcript_urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Signed URLs (1 hour) for every transcript file."
          },
          "transcript_html_urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Signed URLs (1 hour) for HTML transcripts."
          },
          "compliance": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "severity": {
                "type": "string",
                "enum": [
                  "CRITICAL",
                  "WARNING",
                  "CLEAN"
                ]
              },
              "flags": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ComplianceFlag"
                }
              },
              "financials": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "recent_transactions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "explanation": {
                      "type": "string"
                    },
                    "date": {
                      "type": "string"
                    },
                    "amount": {}
                  }
                },
                "description": "Up to 10, newest first."
              }
            }
          },
          "tax_compliance": {
            "$ref": "#/components/schemas/TaxCompliance"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "qoe_qualification": {
            "$ref": "#/components/schemas/QoeQualification"
          },
          "sandbox": {
            "$ref": "#/components/schemas/SandboxInfo"
          }
        }
      },
      "TranscriptResultDefault": {
        "type": "object",
        "description": "Default shape (no `schema` parameter and no account default).",
        "required": [
          "request_id",
          "status",
          "request_status",
          "entities"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Echoes your request_token (not the ModernTax request UUID)."
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "pending"
            ]
          },
          "request_status": {
            "type": "string",
            "description": "Raw request status."
          },
          "created_at": {
            "type": "string"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TranscriptResultEntity"
            }
          }
        }
      },
      "ShapedEntityMinimal": {
        "type": "object",
        "description": "`schema=minimal`. Only the transcripts you ordered (form + years).",
        "required": [
          "id",
          "name",
          "years_filed",
          "years_unfiled",
          "flags",
          "pdf",
          "html"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "form": {
            "type": [
              "string",
              "null"
            ]
          },
          "years": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "years_filed": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "years_unfiled": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "flags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComplianceFlag"
            }
          },
          "pdf": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Signed URLs (1 hour) for the ordered transcripts (PDF)."
          },
          "html": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Signed URLs (1 hour) for the ordered transcripts (HTML)."
          },
          "tax_compliance": {
            "$ref": "#/components/schemas/TaxCompliance"
          },
          "sandbox": {
            "$ref": "#/components/schemas/SandboxInfo"
          }
        }
      },
      "YearFinancials": {
        "type": "object",
        "properties": {
          "gross_receipts": {
            "type": [
              "number",
              "null"
            ]
          },
          "total_income": {
            "type": [
              "number",
              "null"
            ]
          },
          "total_deductions": {
            "type": [
              "number",
              "null"
            ]
          },
          "total_tax": {
            "type": [
              "number",
              "null"
            ]
          },
          "account_balance": {
            "type": [
              "number",
              "null"
            ]
          },
          "accrued_interest": {
            "type": [
              "number",
              "null"
            ]
          },
          "accrued_penalty": {
            "type": [
              "number",
              "null"
            ]
          },
          "account_balance_plus_accruals": {
            "type": [
              "number",
              "null"
            ]
          },
          "year": {
            "type": "string"
          },
          "form": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ShapedEntityUnderwriting": {
        "type": "object",
        "description": "`schema=underwriting`: minimal plus parsed financials, liabilities, repayment plan and severity.",
        "required": [
          "id",
          "name",
          "years_filed",
          "years_unfiled",
          "flags",
          "pdf",
          "html",
          "financials",
          "tax_liabilities"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "form": {
            "type": [
              "string",
              "null"
            ]
          },
          "years": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "years_filed": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "years_unfiled": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "flags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComplianceFlag"
            }
          },
          "pdf": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Signed URLs (1 hour) for the ordered transcripts (PDF)."
          },
          "html": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Signed URLs (1 hour) for the ordered transcripts (HTML)."
          },
          "tax_compliance": {
            "$ref": "#/components/schemas/TaxCompliance"
          },
          "sandbox": {
            "$ref": "#/components/schemas/SandboxInfo"
          },
          "financials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/YearFinancials"
            }
          },
          "tax_liabilities": {
            "type": "object",
            "properties": {
              "total_assessed": {
                "type": "number"
              },
              "total_paid": {
                "type": "number"
              },
              "total_balance": {
                "type": "number"
              },
              "total_accrued": {
                "type": "number"
              }
            }
          },
          "repayment_plan": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "has_installment_agreement": {
                "type": "boolean"
              },
              "has_offer_in_compromise": {
                "type": "boolean"
              },
              "has_currently_not_collectible": {
                "type": "boolean"
              },
              "details": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "recommendation": {
                "type": "string"
              }
            }
          },
          "overall_severity": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "CRITICAL",
              "WARNING",
              "CLEAN",
              null
            ]
          },
          "headline": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ShapedEntityRaw": {
        "type": "object",
        "description": "`schema=raw`.",
        "required": [
          "id",
          "name",
          "artifacts"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "form": {
            "type": [
              "string",
              "null"
            ]
          },
          "years": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "retrieved_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "artifacts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "pdf",
                    "html",
                    "signed_8821"
                  ]
                },
                "file": {
                  "type": "string"
                },
                "url": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Signed URL (1 hour)."
                },
                "sha256": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Hex SHA-256 of the file, computed at serve time."
                }
              }
            },
            "description": "Every artifact (max 100)."
          },
          "tax_compliance": {
            "$ref": "#/components/schemas/TaxCompliance"
          },
          "sandbox": {
            "$ref": "#/components/schemas/SandboxInfo"
          }
        }
      },
      "TranscriptResultShaped": {
        "type": "object",
        "description": "Returned when `schema` is given or your account has a pinned default schema.",
        "required": [
          "request_id",
          "schema",
          "status",
          "request_status",
          "entities"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Echoes your request_token."
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "Loan number."
          },
          "schema": {
            "type": "string",
            "enum": [
              "minimal",
              "underwriting",
              "raw"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "pending"
            ]
          },
          "request_status": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "entities": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ShapedEntityMinimal"
                },
                {
                  "$ref": "#/components/schemas/ShapedEntityUnderwriting"
                },
                {
                  "$ref": "#/components/schemas/ShapedEntityRaw"
                }
              ]
            }
          }
        }
      },
      "BrokerCheckResponse": {
        "type": "object",
        "required": [
          "check_id",
          "name_match",
          "signals",
          "coverage",
          "price_charged",
          "usage"
        ],
        "properties": {
          "check_id": {
            "type": "string",
            "format": "uuid"
          },
          "name_match": {
            "type": "string",
            "enum": [
              "match",
              "mismatch",
              "unknown"
            ]
          },
          "signals": {
            "type": "object",
            "required": [
              "lien_on_file",
              "outstanding_balance_signal",
              "unfiled_years_signal",
              "overall",
              "summary"
            ],
            "properties": {
              "lien_on_file": {
                "type": "boolean"
              },
              "outstanding_balance_signal": {
                "type": "string",
                "enum": [
                  "none",
                  "balance_due",
                  "unknown"
                ]
              },
              "unfiled_years_signal": {
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string",
                    "const": "unknown"
                  }
                ]
              },
              "overall": {
                "type": "string",
                "enum": [
                  "clear",
                  "caution",
                  "adverse",
                  "no_records"
                ]
              },
              "summary": {
                "type": "string"
              }
            }
          },
          "coverage": {
            "type": "object",
            "properties": {
              "records_on_file": {
                "type": "boolean"
              },
              "years_covered": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "last_record_date": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "price_charged": {
            "type": "number"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "BusinessProfile": {
        "type": "object",
        "properties": {
          "entity_id": {
            "type": "string",
            "format": "uuid"
          },
          "business_name": {
            "type": "string"
          },
          "tin_last4": {
            "type": [
              "string",
              "null"
            ]
          },
          "naics": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "filters": {
            "type": "object",
            "properties": {
              "delegated_authority": {},
              "business_age": {},
              "is_acquisition": {},
              "sold_secondary_market": {},
              "sba_loan_count": {},
              "credit_products": {},
              "other_lenders": {}
            }
          },
          "sba_loans": {},
          "sba_match_confidence": {},
          "transcripts": {
            "description": "Transcript facts for the business."
          },
          "summary_markdown": {
            "type": [
              "string",
              "null"
            ]
          },
          "summary_generated_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "sources": {},
          "refreshed_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "TieOutRun": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "form": {
            "type": "string",
            "enum": [
              "1120S",
              "1065",
              "1120",
              "1040SC"
            ]
          },
          "tax_year": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "no_variances",
              "variances",
              "not_comparable"
            ]
          },
          "headline": {
            "type": "string"
          },
          "requires_review": {
            "type": "boolean",
            "const": true,
            "description": "Always true: Tie-Out never certifies; a person must review every flagged line."
          },
          "blocking_issues": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "counts": {
            "type": "object",
            "properties": {
              "compared": {
                "type": "integer"
              },
              "matched": {
                "type": "integer"
              },
              "variances": {
                "type": "integer"
              },
              "missing": {
                "type": "integer"
              },
              "flagged": {
                "type": "integer"
              }
            }
          },
          "tolerance": {
            "type": "object",
            "properties": {
              "absolute": {
                "type": "number"
              },
              "relative": {
                "type": "number"
              }
            }
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "line": {
                  "type": "string"
                },
                "return_value": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "irs_value": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "difference": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "difference_pct": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "match",
                    "variance",
                    "missing_on_return",
                    "missing_on_irs",
                    "not_reported"
                  ]
                },
                "flagged": {
                  "type": "boolean"
                }
              }
            }
          },
          "return_read": {
            "type": "object",
            "properties": {
              "reader": {},
              "form_as_printed": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "tax_year": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "filename": {
                "type": "string"
              }
            }
          },
          "irs_transcript": {
            "type": "object",
            "properties": {
              "source": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "period_ending": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "run_at": {
            "type": "string"
          },
          "review": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "reviewer_name": {
                "type": "string"
              },
              "reviewer_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "reviewed_at": {
                "type": "string"
              },
              "note": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "EmploymentResult": {
        "type": "object",
        "description": "Short employment summary. Omitted when ModernTax has turned the employment object off.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "complete",
              "no_record",
              "error"
            ]
          },
          "employer_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Highest-paying W-2 employer in the most recent year."
          },
          "employment_status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null today (not available from a Wage & Income transcript)."
          },
          "income_range": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null today."
          },
          "wage_years": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "year": {
                  "type": "string"
                },
                "employer_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "wages": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              }
            }
          },
          "verification_date": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}
