ticexplorer-com Claims API

openapi: 3.2.0
info:
  title: TiC Explorer Claims API
  description: '**TiC Explorer** — negotiated health-care prices from **Transparency in Coverage** files (every in-network rate a plan pays each

    billing entity), Original Medicare fee schedules and, as a secondary source, hospitals'' own price files (each hospital''s

    posted rate per payer/plan as it wrote them, mostly facility charges, and its discounted cash price) — with the billing

    semantics needed to use them correctly: allowed vs billed vs patient share, global vs 26/TC, office vs facility rates, hospital outpatient APC

    case rates and packaging, placeholders and percent-of-charges contracts, and per-row provenance.


    **Start with** `GET /v1/guide` (billing mechanics, field dictionary, worked examples) and `GET /v1/workflows`.


    **Auth:** `Authorization: Bearer `. Get a key in the console at https://ticexplorer.com/dashboard/keys (self-hosted:

    `python -m api keys create` or `POST /v1/admin/keys`). The MCP endpoint `https://api.ticexplorer.com/mcp` accepts the same API keys

    or OAuth 2.1 access tokens, e.g. `claude mcp add --transport http ticexplorer https://api.ticexplorer.com/mcp`.


    **Conventions:** list responses are `{"data": [...], "next_cursor": ...}` (pass `cursor`); errors are

    `{"error": {"code", "message", "hint"}}`; every response has `X-Request-Id`, `X-RateLimit-Limit`,

    `X-RateLimit-Remaining`, `X-RateLimit-Reset`. Responses carry `needs` (missing inputs that change the answer) and

    `next_steps`.'
  version: 0.3.0
servers:
- url: /
tags:
- name: Claims
  description: Price or reconcile a whole visit / bill.
paths:
  /v1/claims/price:
    post:
      tags:
      - Claims
      summary: Price or reconcile a whole claim
      description: 'Many claim lines at one or more candidate billing entities → the rate each entity would be paid per line (APC

        case rates, packaging, office vs facility), totals, and — with `claim_allowed_total` — a reconciliation verdict.


        **Workflows**


        Workflow `estimate-visit-cost`, step 4/4 `price-visit`: Estimate what a visit will cost a person before care, under their plan, at a specific place.

        - Purpose: Prices all expected lines at the candidate billing entities for the given place of service.

        - Call after: `find_codes`


        Workflow `check-a-bill`, step 3/3 `reconcile`: Check whether a received bill or EOB matches the plan''s published negotiated prices.

        - Purpose: Reconciles the claim at the billing entity and related entities; hospital bills are place_of_service hospital_outpatient.

        - Call after: `find_providers`'
      operationId: price_claim
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - HTTPBearer: []
components:
  schemas:
    ClaimLineResult:
      properties:
        code:
          type: string
          title: Code
        units:
          type: number
          title: Units
        status_indicator:
          anyOf:
          - type: string
          - type: 'null'
          title: Status Indicator
        options:
          items:
            $ref: '#/components/schemas/ClaimOption'
          type: array
          title: Options
          description: The rule-based rate each candidate billing entity would be paid.
        expected_range:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Expected Range
        notes:
          items:
            type: string
          type: array
          title: Notes
          default: []
      additionalProperties: true
      type: object
      required:
      - code
      - units
      - options
      title: ClaimLineResult
    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
    ErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine-readable error code, e.g. plan_not_found, invalid_zip, unauthorized.
        message:
          type: string
          title: Message
        hint:
          type: string
          title: Hint
          default: ''
      type: object
      required:
      - code
      - message
      title: ErrorBody
    Need:
      properties:
        field:
          type: string
          title: Field
          description: The missing input or condition, e.g. which_insurer, place_of_service, wait.
        why:
          type: string
          title: Why
          description: Why it changes the answer and what to do.
      additionalProperties: true
      type: object
      required:
      - field
      - why
      title: Need
    ClaimOption:
      properties:
        tin:
          anyOf:
          - type: string
          - type: 'null'
          title: Tin
        entity:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity
        amount:
          anyOf:
          - type: number
          - type: 'null'
          title: Amount
        method:
          type: string
          title: Method
        confidence:
          type: string
          title: Confidence
      additionalProperties: true
      type: object
      required:
      - method
      - confidence
      title: ClaimOption
    ClaimRequest:
      properties:
        coverage:
          $ref: '#/components/schemas/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
          examples:
          - '98052'
        lines:
          items:
            $ref: '#/components/schemas/ClaimLine'
          type: array
          maxItems: 40
          minItems: 1
          title: Lines
        billing_entities:
          items:
            $ref: '#/components/schemas/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
      title: ClaimRequest
    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
    ClaimResult:
      properties:
        lines:
          items:
            $ref: '#/components/schemas/ClaimLineResult'
          type: array
          title: Lines
        billing_entities:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Billing Entities
        per_entity_totals:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Per Entity Totals
        expected_total_range:
          items:
            type: number
          type: array
          title: Expected Total Range
        reconciliation:
          anyOf:
          - $ref: '#/components/schemas/Reconciliation'
          - type: 'null'
        needs:
          items:
            $ref: '#/components/schemas/Need'
          type: array
          title: Needs
          default: []
        next_steps:
          items:
            type: string
          type: array
          title: Next Steps
          default: []
      additionalProperties: true
      type: object
      required:
      - lines
      - billing_entities
      - per_entity_totals
      - expected_total_range
      title: ClaimResult
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: Error
    Reconciliation:
      properties:
        actual_allowed_total:
          type: number
          title: Actual Allowed Total
        best_match_total:
          type: number
          title: Best Match Total
        difference:
          type: number
          title: Difference
        difference_percent:
          type: number
          title: Difference Percent
        verdict:
          type: string
          enum:
          - explained
          - plausible
          - unexplained
          title: Verdict
        best_match:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Best Match
        explanation:
          type: string
          title: Explanation
        interpretation:
          type: string
          title: Interpretation
        caveat:
          type: string
          title: Caveat
      additionalProperties: true
      type: object
      required:
      - actual_allowed_total
      - best_match_total
      - difference
      - difference_percent
      - verdict
      - best_match
      - explanation
      - interpretation
      - caveat
      title: Reconciliation
    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
  securitySchemes:
    HTTPBearer:
      type: http
      description: API key (tic_live_...) or OAuth access token.
      scheme: bearer
    oauth2:
      type: oauth2
      description: OAuth 2.1 (authorization code + PKCE) for MCP clients; see /.well-known/oauth-authorization-server
      flows:
        authorizationCode:
          authorizationUrl: /authorize
          tokenUrl: /token
          scopes:
            read: Query prices
x-workflow-renderer: builtin