ClaimRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ticexplorer-com/json-schema/ticexplorer-com-claim-request-schema.json",
  "title": "ClaimRequest",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ticexplorer-com-openapi.json#/components/schemas/ClaimRequest",
  "properties": {
    "coverage": {
      "$ref": "#/$defs/Coverage",
      "description": "type plan (with plan_id) or medicare. type hospital is rejected (400 claim_coverage_unsupported): hospital price-file rates are per code; use get_rates."
    },
    "zip": {
      "type": "string",
      "title": "Zip"
    },
    "lines": {
      "items": {
        "$ref": "#/$defs/ClaimLine"
      },
      "type": "array",
      "maxItems": 40,
      "minItems": 1,
      "title": "Lines"
    },
    "billing_entities": {
      "items": {
        "$ref": "#/$defs/Entity"
      },
      "type": "array",
      "title": "Billing Entities",
      "description": "Candidate billing entities (TINs); each line is priced at each. Include the owning hospital's TIN for hospital-owned clinics."
    },
    "place_of_service": {
      "type": "string",
      "enum": [
        "office",
        "hospital_outpatient",
        "facility",
        "unknown"
      ],
      "title": "Place Of Service",
      "description": "office = clinic / urgent care / doctor's office (\"physician services\"); hospital_outpatient = hospital outpatient department, hospital imaging or lab (\"hospital services\").",
      "default": "unknown"
    },
    "claim_allowed_total": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Claim Allowed Total",
      "description": "Actual allowed amount from the bill/EOB, to reconcile."
    },
    "miles": {
      "type": "number",
      "maximum": 100.0,
      "minimum": 1.0,
      "title": "Miles",
      "default": 15
    },
    "wait_seconds": {
      "type": "integer",
      "maximum": 240.0,
      "minimum": 5.0,
      "title": "Wait Seconds",
      "default": 90
    }
  },
  "type": "object",
  "required": [
    "coverage",
    "zip",
    "lines"
  ],
  "$defs": {
    "ClaimLine": {
      "properties": {
        "code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Code",
          "description": "CPT/HCPCS code on the bill (from the bill/EOB or find_codes). Leave empty when a hospital bill shows only a revenue category, and give revenue_category instead."
        },
        "revenue_category": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Revenue Category",
          "description": "For hospital bills without codes: the line as printed, e.g. \"Radiology - Diagnostic\", \"Laboratory\", \"Emergency Room\", \"CT scan\", \"Pharmacy\". Priced as each hospital outpatient payment group (APC) that category can be; reconciliation then shows which one matches the allowed amount."
        },
        "units": {
          "type": "number",
          "exclusiveMinimum": 0.0,
          "title": "Units",
          "default": 1
        },
        "modifiers": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Modifiers",
          "description": "e.g. [\"26\"] or [\"TC\"]."
        },
        "billed": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Billed",
          "description": "Billed charge for the line (needed for percent-of-charges contracts)."
        },
        "allowed": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Allowed",
          "description": "Allowed amount for this line from the EOB, if shown."
        }
      },
      "type": "object",
      "title": "ClaimLine"
    },
    "Coverage": {
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "plan",
            "medicare",
            "hospital"
          ],
          "title": "Type",
          "description": "plan = a plan from find_plan (insurer rate files); medicare = Original Medicare fee schedule; hospital = hospitals' own price files (Medicare Advantage, Medicaid, cash/self-pay): each hospital's posted rate per payer/plan as the hospital wrote it (not necessarily the person's plan), mostly facility charges; cash = its discounted cash price, not the gross charge. price_claim does not accept hospital.",
          "default": "plan"
        },
        "plan_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Plan Id",
          "description": "Required when type = plan; from find_plan."
        },
        "hospital_coverage": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Hospital Coverage",
          "description": "For type = hospital: medicare_advantage | medicaid | cash | a payer name."
        }
      },
      "type": "object",
      "title": "Coverage"
    },
    "Entity": {
      "properties": {
        "tin": {
          "type": "string",
          "title": "Tin",
          "description": "Billing entity tax ID from find_providers (billing_entities or related_entities)."
        }
      },
      "type": "object",
      "required": [
        "tin"
      ],
      "title": "Entity"
    }
  }
}