{
  "openapi": "3.1.0",
  "info": {
    "title": "eobs.claims: the Explanation of Benefits as a typed read surface",
    "version": "0.1.0-earlyaccess",
    "description": "EARLY ACCESS STUB. This spec documents the typed shape of the EOB (Explanation of Benefits, a health revenue-cycle document) and the operations planned over it. NO OPERATION IN THIS SPEC IS CALLABLE YET: every operation is tagged x-status roadmap. The schema components are the free, keyless reference content of eobs.claims. Contact hello@api.insure for early access.",
    "contact": {
      "name": "api.insure estate",
      "email": "hello@api.insure",
      "url": "https://eobs.claims"
    }
  },
  "servers": [
    {
      "url": "https://eobs.claims",
      "description": "Serves this spec and the reference pages today. No API operation below is live; all are roadmap."
    }
  ],
  "paths": {
    "/schema": {
      "get": {
        "operationId": "getEobSchema",
        "summary": "Return the Eob JSON Schema (ROADMAP, not yet callable)",
        "description": "ROADMAP. Not yet callable. Will return the canonical JSON Schema for the Eob shape. Until then, the schema is published inline in this document under components.schemas.Eob.",
        "x-status": "roadmap",
        "responses": {
          "200": {
            "description": "The Eob schema.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Eob"
                }
              }
            }
          }
        }
      }
    },
    "/parse": {
      "post": {
        "operationId": "parseEob",
        "summary": "Parse an EOB document into the typed schema (ROADMAP, not yet callable)",
        "description": "ROADMAP. Not yet callable. Will accept an EOB PDF or an X12 835 remittance and return the typed Eob shape.",
        "x-status": "roadmap",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "document": {
                    "type": "string",
                    "format": "binary",
                    "description": "EOB PDF or X12 835 remittance file."
                  }
                },
                "required": [
                  "document"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The parsed EOB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Eob"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Eob": {
        "type": "object",
        "description": "An Explanation of Benefits: the statement a health plan sends a member after it processes a claim. Not a bill; any bill comes from the provider.",
        "required": [
          "payer",
          "member_id",
          "claim_number",
          "provider",
          "date_processed",
          "lines",
          "totals"
        ],
        "properties": {
          "payer": {
            "type": "string",
            "description": "The health plan that processed the claim."
          },
          "member_id": {
            "type": "string"
          },
          "claim_number": {
            "type": "string",
            "description": "The plan's claim identifier. Appeals reference it."
          },
          "provider": {
            "type": "string",
            "description": "Who rendered and billed the services."
          },
          "date_processed": {
            "type": "string",
            "format": "date",
            "description": "When the plan finished processing the claim."
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EobServiceLine"
            }
          },
          "totals": {
            "$ref": "#/components/schemas/EobTotals"
          },
          "appeal_window": {
            "$ref": "#/components/schemas/EobAppealWindow"
          }
        }
      },
      "EobServiceLine": {
        "type": "object",
        "required": [
          "date_of_service",
          "procedure_code",
          "billed",
          "allowed",
          "plan_paid",
          "patient_responsibility"
        ],
        "properties": {
          "date_of_service": {
            "type": "string",
            "format": "date"
          },
          "procedure_code": {
            "type": "string",
            "description": "CPT or HCPCS code for the service line."
          },
          "description": {
            "type": "string",
            "description": "Plain-language service description."
          },
          "billed": {
            "type": "number",
            "description": "USD the provider charged."
          },
          "allowed": {
            "type": "number",
            "description": "The plan's negotiated rate: the contract number, not the sticker number."
          },
          "plan_paid": {
            "type": "number",
            "description": "USD the plan paid the provider on this line."
          },
          "patient_responsibility": {
            "type": "number",
            "description": "Copay, coinsurance, or deductible: what the member may owe the provider. The EOB itself is not a bill."
          },
          "remark_codes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "CARC/RARC codes explaining any reduction or non-payment, e.g. CO-45, CO-97, PR-1."
          }
        }
      },
      "EobTotals": {
        "type": "object",
        "required": [
          "billed",
          "allowed",
          "plan_paid",
          "patient_responsibility"
        ],
        "properties": {
          "billed": {
            "type": "number"
          },
          "allowed": {
            "type": "number"
          },
          "plan_paid": {
            "type": "number"
          },
          "patient_responsibility": {
            "type": "number"
          }
        }
      },
      "EobAppealWindow": {
        "type": "object",
        "description": "The plan's appeal deadline and address, when stated on the document.",
        "properties": {
          "deadline": {
            "type": "string",
            "format": "date"
          },
          "days": {
            "type": "integer",
            "description": "Days from date_processed, commonly 180 for internal appeals; varies by plan and state."
          },
          "address": {
            "type": "string"
          }
        }
      }
    }
  }
}