ticexplorer-com Plans API

openapi: 3.2.0
info:
  title: TiC Explorer Plans 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: Plans
  description: Which plan (and rate files) applies to a person.
paths:
  /v1/plans:
    get:
      tags:
      - Plans
      summary: Find a health plan
      description: 'Employer / insurer / plan name / EIN / marketplace plan id → plans, with the `plan_id` used by rates and claims.


        **Workflows**


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

        - Purpose: Resolves the person''s plan; one employer can map to several insurers, and the ID card names the one that applies.

        - Next: `find_providers`


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

        - Next: `find_providers`


        Workflow `compare-places`, step 1/3 `resolve-plan`: Compare what the plan pays different nearby providers for the same service.

        - Next: `find_codes`'
      operationId: find_plan
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          description: Employer, insurer, plan name, EIN or HIOS id
          examples:
          - microsoft premera
          title: Q
        description: Employer, insurer, plan name, EIN or HIOS id
      - name: zip
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Member ZIP (ranks plans in that state first)
          title: Zip
        description: Member ZIP (ranks plans in that state first)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 10
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanList'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Too Many Requests
  /v1/plans/{plan_id}:
    get:
      tags:
      - Plans
      summary: Get a plan and its rate files
      operationId: get_plan
      security:
      - HTTPBearer: []
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
          title: Plan Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanDetail'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Too Many Requests
components:
  schemas:
    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
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: Error
    PlanDetail:
      properties:
        plan:
          additionalProperties: true
          type: object
          title: Plan
        rate_files:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Rate Files
      additionalProperties: true
      type: object
      required:
      - plan
      - rate_files
      title: PlanDetail
    PlanList:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Plan'
          type: array
          title: Data
        next_cursor:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Cursor
        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:
      - data
      title: PlanList
    Plan:
      properties:
        plan_id:
          type: string
          title: Plan Id
          description: Pass as coverage.plan_id.
        payer:
          type: string
          title: Payer
        plan_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Name
        sponsor_employer:
          anyOf:
          - type: string
          - type: 'null'
          title: Sponsor Employer
        sponsor_location:
          anyOf:
          - type: string
          - type: 'null'
          title: Sponsor Location
        plan_id_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Id Type
          description: ein (employer plan) or hios (marketplace) ...
        plan_identifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Identifier
        market:
          anyOf:
          - type: string
          - type: 'null'
          title: Market
        rate_files:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rate Files
        price_source:
          type: string
          title: Price Source
      additionalProperties: true
      type: object
      required:
      - plan_id
      - payer
      - price_source
      title: Plan
  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