MedReveal Provider API

openapi: 3.2.0
info:
  title: MedReveal Provider 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: provider-api
  description: 💰 Provider-specific rate search endpoints
paths:
  /api/v1/provider/searchrates:
    post:
      tags:
      - provider-api
      summary: Search Provider Rates
      description: 'Search for provider-specific rates.


        Returns negotiated rates for specific providers (NPIs or TINs) with

        optional filtering and grouping capabilities.


        **Required Parameters:**

        - insurance: Insurance company code (uhc, cigna, aetna, bcbs)

        - npis OR tins: At least one must be provided


        **Optional Parameters:**

        - billingCodeAndTypes: List of billing codes with types

        - billingCodeModifiers: List of billing code modifiers

        - serviceCodes: List of service codes

        - billingClasses: List of billing classes

        - negotiatedTypes: List of negotiated types

        - groupBy: Fields to group results by


        **Response Fields (when not grouped):**

        - payer, npi, tin_value, provider_name, provider_state, provider_city

        - provider_postal_code, primary_taxonomy_code, entity_type

        - billing_code, billing_code_type, billing_class, negotiated_type

        - service_code, billing_code_modifier, negotiated_rate


        **Rate Limits:**

        - BASE: Max 10 NPIs, 5 TINs, 10 billing codes

        - PREMIUM: Max 100 NPIs, 50 TINs, 50 billing codes'
      operationId: search_provider_rates_api_v1_provider_searchrates_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderSearchRatesRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderSearchRatesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/provider/searchrates/info:
    get:
      tags:
      - provider-api
      summary: Get Provider Search Info
      description: 'Get information about the provider search rates endpoint.


        Returns available payers, groupBy fields, and role-based limits.'
      operationId: get_provider_search_info_api_v1_provider_searchrates_info_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    ProviderSearchGroupByField:
      type: string
      enum:
      - payer
      - npi_state
      - taxonomy_code
      - entity_type
      - billing_code
      - billing_code_type
      - billing_class
      - negotiated_type
      - billing_code_modifier
      title: ProviderSearchGroupByField
      description: Valid fields for grouping provider search results.
    ProviderSearchRatesData:
      properties:
        results:
          items:
            type: object
          type: array
          title: Results
        summary:
          $ref: '#/components/schemas/ProviderSearchRatesSummary'
      type: object
      required:
      - results
      - summary
      title: ProviderSearchRatesData
      description: Data container for provider search rates response.
    ProviderSearchRatesResponse:
      properties:
        success:
          type: boolean
          title: Success
        data:
          anyOf:
          - $ref: '#/components/schemas/ProviderSearchRatesData'
          - type: 'null'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        pagination:
          anyOf:
          - $ref: '#/components/schemas/PaginationInfo'
          - type: 'null'
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - success
      - meta
      title: ProviderSearchRatesResponse
      description: Response for provider search rates.
    ProviderSearchRatesRequest:
      properties:
        insurance:
          type: string
          title: Insurance
          description: Insurance company code (uhc, cigna, aetna, bcbs, optum)
        npis:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Npis
          description: List of NPIs to search (required if tins not provided)
        tins:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tins
          description: List of TINs to search (required if npis not provided)
        billingCodeAndTypes:
          anyOf:
          - items:
              $ref: '#/components/schemas/BillingCodeWithType'
            type: array
          - type: 'null'
          title: Billingcodeandtypes
          description: List of billing codes with types
        billingCodeModifiers:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Billingcodemodifiers
          description: List of billing code modifiers
        serviceCodes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Servicecodes
          description: List of service codes
        billingClasses:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Billingclasses
          description: List of billing classes
        negotiatedTypes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Negotiatedtypes
          description: List of negotiated types
        groupBy:
          anyOf:
          - items:
              $ref: '#/components/schemas/ProviderSearchGroupByField'
            type: array
          - type: 'null'
          title: Groupby
          description: Fields to group results by
        page:
          type: integer
          minimum: 1.0
          title: Page
          description: Page number (1-indexed)
          default: 1
        pageSize:
          type: integer
          maximum: 1000.0
          minimum: 1.0
          title: Pagesize
          description: Results per page
          default: 100
      type: object
      required:
      - insurance
      title: ProviderSearchRatesRequest
      description: 'Request for provider-specific rate searches.


        Requires either npis OR tins (at least one must be provided).'
    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.
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProviderSearchRatesSummary:
      properties:
        totalResults:
          type: integer
          title: Totalresults
        totalRecordsAnalyzed:
          type: integer
          title: Totalrecordsanalyzed
      type: object
      required:
      - totalResults
      - totalRecordsAnalyzed
      title: ProviderSearchRatesSummary
      description: Summary statistics for provider search results.
    PaginationInfo:
      properties:
        page:
          type: integer
          title: Page
        pageSize:
          type: integer
          title: Pagesize
        totalResults:
          type: integer
          title: Totalresults
        totalPages:
          type: integer
          title: Totalpages
      type: object
      required:
      - page
      - pageSize
      - totalResults
      - totalPages
      title: PaginationInfo
      description: Pagination information for list responses.
    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).