MedReveal Benchmarking API

openapi: 3.2.0
info:
  title: MedReveal Benchmarking API
  description: '## Healthcare Price Transparency API


    MedReveal API provides access to healthcare provider rate data, enabling you to build powerful analytics and price transparency tools.


    ### 🔐 Authentication


    Protected endpoints require an API key. Include your key in the request header:


    ```

    X-API-Key: your_api_key_here

    ```


    ### ⚡ Rate Limits


    | Tier | Daily Limit | Rate Limit |

    |------|-------------|------------|

    | BASE | 100 requests/day | 10 requests/minute |

    | PREMIUM | 10,000 requests/day | 100 requests/minute |


    ### 📚 Core Endpoints


    | Endpoint | Description |

    |----------|-------------|

    | `/api/v1/npis/{npi}` | Lookup provider by NPI |

    | `/api/v1/tins/{tin}` | Lookup provider group by TIN |

    | `/api/v1/market/benchmarking` | Get market benchmark statistics |

    | `/api/v1/provider/searchrates` | Search provider-specific rates |

    | `/api/v1/taxonomy/{code}` | Lookup taxonomy code details |


    ### 🌐 Website


    med-reveal.com | Developer Docs'
  version: 1.0.0
tags:
- name: benchmarking-api
paths:
  /api/v1/market/benchmarking:
    post:
      tags:
      - benchmarking-api
      summary: Get Market Benchmarks
      description: 'Get market benchmark statistics grouped by payer and billing code.


        Returns percentile statistics (mean, median, p25, p50, p75, p90, p95)

        for negotiated rates across specified payers, states, and billing codes.


        **Rate Limits:**

        - BASE: Max 2 payers, 5 billing codes, 1 state per request

        - PREMIUM: Max 10 payers, 50 billing codes, 10 states per request


        **Request Body:**

        - filters.payers: List of payer codes (uhc, cigna, aetna, bcbs)

        - filters.states: List of state codes

        - filters.billingCodeAndTypes: List of billing codes with types

        - filters.taxonomyCodes: Optional taxonomy codes to filter by

        - filters.serviceCodes: Optional service codes to filter by

        - filters.billingCodeModifiers: Optional billing code modifiers to filter by

        - filters.negotiatedTypes: Optional negotiated types to filter by

        - filters.billingClasses: Optional billing classes to filter by

        - metrics.aggregations: List of aggregations to compute

        - groupBy: Fields to group by (payer, billing_code, state)


        **Returns:**

        Grouped benchmark statistics with mean, median, percentiles, min, max, count.'
      operationId: get_market_benchmarks_api_v1_market_benchmarking_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenchmarkRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/market/benchmarking/info:
    get:
      tags:
      - benchmarking-api
      summary: Get Benchmarking Info
      description: 'Get information about the benchmarking endpoint.


        Returns available payers, supported aggregations, and role-based limits.'
      operationId: get_benchmarking_info_api_v1_market_benchmarking_info_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    BillingCodeWithType:
      properties:
        code:
          type: string
          title: Code
          description: Billing code (e.g., '99213')
        type:
          type: string
          title: Type
          description: 'Code type: ''CPT'' or ''HCPCS'''
      type: object
      required:
      - code
      - type
      title: BillingCodeWithType
      description: Billing code with its type (CPT or HCPCS).
    ResponseMeta:
      properties:
        requestId:
          type: string
          title: Requestid
        timestamp:
          type: string
          title: Timestamp
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        dailyLimit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Dailylimit
        remainingToday:
          anyOf:
          - type: integer
          - type: 'null'
          title: Remainingtoday
        processingTime:
          anyOf:
          - type: string
          - type: 'null'
          title: Processingtime
      type: object
      required:
      - requestId
      - timestamp
      title: ResponseMeta
      description: Standard response metadata.
    BenchmarkMetrics:
      properties:
        aggregations:
          items:
            type: string
          type: array
          title: Aggregations
          description: List of aggregations to compute
          default:
          - mean
          - median
          - percentile_25
          - percentile_50
          - percentile_75
          - percentile_90
          - percentile_95
      type: object
      title: BenchmarkMetrics
      description: Metrics configuration for benchmarking.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BenchmarkFilters:
      properties:
        states:
          items:
            type: string
          type: array
          minItems: 1
          title: States
          description: List of state codes (e.g., ['MA', 'TX'])
        payers:
          items:
            type: string
          type: array
          minItems: 1
          title: Payers
          description: 'List of payer codes: uhc, cigna, aetna, bcbs'
        billingCodeAndTypes:
          items:
            $ref: '#/components/schemas/BillingCodeWithType'
          type: array
          minItems: 1
          title: Billingcodeandtypes
          description: List of billing codes with types
        taxonomyCodes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Taxonomycodes
          description: List of taxonomy codes
        serviceCodes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Servicecodes
          description: List of service codes
        billingCodeModifiers:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Billingcodemodifiers
          description: List of billing code modifiers
        negotiatedTypes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Negotiatedtypes
          description: Filter by negotiated types (e.g., 'negotiated', 'fee schedule')
        billingClasses:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Billingclasses
          description: Filter by billing classes (e.g., 'professional')
      type: object
      required:
      - states
      - payers
      - billingCodeAndTypes
      title: BenchmarkFilters
      description: Filters for benchmarking query.
    BenchmarkRequest:
      properties:
        filters:
          $ref: '#/components/schemas/BenchmarkFilters'
        metrics:
          anyOf:
          - $ref: '#/components/schemas/BenchmarkMetrics'
          - type: 'null'
          description: Metrics configuration
        groupBy:
          items:
            type: string
          type: array
          title: Groupby
          description: 'Fields to group by: ''payer'', ''billing_code'', ''state'''
          default:
          - payer
          - billing_code
      type: object
      required:
      - filters
      title: BenchmarkRequest
      description: Request for market benchmarking.
    BenchmarkSummary:
      properties:
        totalGroups:
          type: integer
          title: Totalgroups
        totalRecordsAnalyzed:
          type: integer
          title: Totalrecordsanalyzed
      type: object
      required:
      - totalGroups
      - totalRecordsAnalyzed
      title: BenchmarkSummary
      description: Summary statistics for benchmarking response.
    BenchmarkResponse:
      properties:
        success:
          type: boolean
          title: Success
        data:
          anyOf:
          - $ref: '#/components/schemas/BenchmarkData'
          - type: 'null'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - success
      - meta
      title: BenchmarkResponse
      description: Response for market benchmarking.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BenchmarkData:
      properties:
        benchmarks:
          items:
            $ref: '#/components/schemas/BenchmarkResult'
          type: array
          title: Benchmarks
        summary:
          $ref: '#/components/schemas/BenchmarkSummary'
      type: object
      required:
      - benchmarks
      - summary
      title: BenchmarkData
      description: Data container for benchmarking response.
    BenchmarkResult:
      properties:
        payer:
          type: string
          title: Payer
        billingCode:
          type: string
          title: Billingcode
        billingCodeType:
          type: string
          title: Billingcodetype
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
        mean:
          anyOf:
          - type: number
          - type: 'null'
          title: Mean
        median:
          anyOf:
          - type: number
          - type: 'null'
          title: Median
        percentile25:
          anyOf:
          - type: number
          - type: 'null'
          title: Percentile25
        percentile50:
          anyOf:
          - type: number
          - type: 'null'
          title: Percentile50
        percentile75:
          anyOf:
          - type: number
          - type: 'null'
          title: Percentile75
        percentile90:
          anyOf:
          - type: number
          - type: 'null'
          title: Percentile90
        percentile95:
          anyOf:
          - type: number
          - type: 'null'
          title: Percentile95
        min:
          anyOf:
          - type: number
          - type: 'null'
          title: Min
        max:
          anyOf:
          - type: number
          - type: 'null'
          title: Max
        count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Count
      type: object
      required:
      - payer
      - billingCode
      - billingCodeType
      title: BenchmarkResult
      description: Individual benchmark result for a group.