ticexplorer-com Providers API

openapi: 3.2.0
info:
  title: TiC Explorer Providers 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: Providers
  description: Places and clinicians → billing entities (TINs).
paths:
  /v1/providers:
    get:
      tags:
      - Providers
      summary: Resolve a place/clinician into locations, billing entities and hospital…
      operationId: find_providers
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Name or street address, e.g. "uchealth urgent care" or "1635 Aurora Ct"
          title: Q
        description: Name or street address, e.g. "uchealth urgent care" or "1635 Aurora Ct"
      - name: zip
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 5-digit ZIP to search near
          title: Zip
        description: 5-digit ZIP to search near
      - name: miles
        in: query
        required: false
        schema:
          type: number
          maximum: 100
          minimum: 0.5
          default: 10
          title: Miles
      - name: npi
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Npi
      - name: tin
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Billing entity tax ID
          title: Tin
        description: Billing entity tax ID
      - name: plan_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'From find_plan: needed for billing entities (TINs)'
          title: Plan Id
        description: 'From find_plan: needed for billing entities (TINs)'
      - name: codes
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Comma-separated codes: Medicare billing evidence, or list who near the ZIP bills them when q is empty'
          title: Codes
        description: 'Comma-separated codes: Medicare billing evidence, or list who near the ZIP bills them when q is empty'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          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/ProvidersResult'
        '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
      description: '**Workflows**


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

        - Purpose: Turns the place into billing entities (TINs), including related entities such as an owning hospital.

        - Call after: `find_plan`

        - Next: `find_codes`


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

        - Purpose: Includes related_entities, since a hospital-owned clinic''s labs/imaging are often billed by the hospital.

        - Call after: `find_plan`

        - Next: `price_claim`'
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
    Affiliation:
      properties:
        status:
          type: string
          enum:
          - is_hospital
          - likely_hospital_owned
          - possible_hospital_affiliation
          - none_found
          title: Status
        evidence:
          items:
            type: string
          type: array
          title: Evidence
          default: []
        meaning:
          type: string
          title: Meaning
          default: ''
      additionalProperties: true
      type: object
      required:
      - status
      title: Affiliation
    RelatedEntity:
      properties:
        tin:
          type: string
          title: Tin
        name:
          type: string
          title: Name
        is_hospital:
          type: boolean
          title: Is Hospital
        shared_clinicians:
          type: integer
          title: Shared Clinicians
        why:
          type: string
          title: Why
        hospital_affiliation:
          anyOf:
          - $ref: '#/components/schemas/Affiliation'
          - type: 'null'
      additionalProperties: true
      type: object
      required:
      - tin
      - name
      - is_hospital
      - shared_clinicians
      - why
      title: RelatedEntity
    ProvidersResult:
      properties:
        locations:
          items:
            $ref: '#/components/schemas/Location'
          type: array
          title: Locations
        next_cursor:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Cursor
        billing_entities:
          items:
            $ref: '#/components/schemas/BillingEntity'
          type: array
          title: Billing Entities
          default: []
        related_entities:
          items:
            $ref: '#/components/schemas/RelatedEntity'
          type: array
          title: Related Entities
          default: []
        sites:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Sites
          description: 'Best sites across billing entities: a city named in the query first, then entity rank, service fit and distance to the site.'
          default: []
        other_name_matches:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Other Name Matches
          description: Same-word names of a different specialty (dental, eye, …) set aside.
          default: []
        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:
      - locations
      title: ProvidersResult
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: Error
    BillingEntity:
      properties:
        tin:
          type: string
          title: Tin
        name:
          type: string
          title: Name
        is_hospital:
          type: boolean
          title: Is Hospital
        clinicians_on_roster:
          anyOf:
          - type: integer
          - type: 'null'
          title: Clinicians On Roster
        matches_location_npis:
          anyOf:
          - type: integer
          - type: 'null'
          title: Matches Location Npis
        hospital_affiliation:
          anyOf:
          - $ref: '#/components/schemas/Affiliation'
          - type: 'null'
        health_system:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Health System
          description: '{name, ccn, ownership, source}: source = why (the entity is the hospital / shares clinicians with a hospital TIN / name match only).'
        ccn:
          anyOf:
          - type: string
          - type: 'null'
          title: Ccn
          description: CMS Certification Number when the entity is an identified hospital.
        sites:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Sites
          description: 'Places to go near the ZIP: organization NPI / practice address / hospital campus with address, taxonomy, miles to the site, fit for the service.'
          default: []
      additionalProperties: true
      type: object
      required:
      - tin
      - name
      - is_hospital
      title: BillingEntity
    Location:
      properties:
        npi:
          type: string
          title: Npi
        kind:
          type: string
          enum:
          - organization
          - individual
          title: Kind
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        specialty:
          anyOf:
          - type: string
          - type: 'null'
          title: Specialty
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        miles:
          anyOf:
          - type: number
          - type: 'null'
          title: Miles
        medicare_billed_2024:
          anyOf:
          - additionalProperties:
              type: integer
            type: object
          - type: 'null'
          title: Medicare Billed 2024
          description: Medicare CY2024 services billed per code by this NPI.
      additionalProperties: true
      type: object
      required:
      - npi
      - kind
      title: Location
  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