openapi: 3.0.1
info:
  title: Serif Health Pricing Distributions API
  description: 'REST API for Serif Health''s normalized healthcare price-transparency data. Query payer-negotiated reimbursement rates and percentile rate distributions for an individual procedure code (CPT/DRG), filtered by region, tier, site of service, payer, and weighting. Rates are derived from federally mandated machine-readable files (MRFs) published by payers and hospitals.

    Only the rates and distributions endpoints are documented here from public Serif Health materials. Find Care, Provider Directory, and dataset/extract capabilities are offered but their request/response contracts are not publicly documented and are intentionally not fabricated here.'
  termsOfService: https://www.serifhealth.com/legal/terms
  contact:
    name: Serif Health
    email: hello@serifhealth.com
    url: https://www.serifhealth.com
  version: '1.0'
servers:
- url: https://pricing-api.serifhealth.com
  description: Serif Health Pricing API
security:
- ApiKeyAuth: []
tags:
- name: Distributions
paths:
  /v1/distributions/code/{code}:
    get:
      operationId: getDistributionsByCode
      tags:
      - Distributions
      summary: Get rate distribution for a procedure code
      description: Returns the percentile distribution (5th-95th) of negotiated rates for a single procedure code, filtered by region, tier, site of service, payer, and weighting method.
      parameters:
      - name: code
        in: path
        required: true
        description: The procedure code (CPT or DRG) to look up.
        schema:
          type: string
        example: '90837'
      - name: region
        in: query
        required: false
        description: US state abbreviation to scope the distribution to (e.g. TX).
        schema:
          type: string
        example: TX
      - name: tier
        in: query
        required: false
        description: Service tier, e.g. professional or facility.
        schema:
          type: string
        example: professional
      - name: site
        in: query
        required: false
        description: Site of service, e.g. nonfac (non-facility) or fac (facility).
        schema:
          type: string
        example: nonfac
      - name: payer
        in: query
        required: false
        description: Payer name to filter to (e.g. bcbs, cigna, uhc).
        schema:
          type: string
        example: bcbs
      - name: weighting
        in: query
        required: false
        description: Weighting method for the distribution, by ein or npi.
        schema:
          type: string
          enum:
          - ein
          - npi
        example: ein
      responses:
        '200':
          description: Percentile rate distribution for the requested code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistributionResponse'
        '401':
          description: Missing or invalid API key.
        '404':
          description: No distribution found for the requested code/filters.
        '429':
          description: Rate limit exceeded.
components:
  schemas:
    Percentiles:
      type: object
      description: Negotiated-rate percentiles in USD.
      properties:
        5th:
          type: number
          example: 92.04
        10th:
          type: number
          example: 92.04
        25th:
          type: number
          example: 103.06
        50th:
          type: number
          example: 126.69
        75th:
          type: number
          example: 133.86
        90th:
          type: number
          example: 162.07
        95th:
          type: number
          example: 179.27
    DistributionResponse:
      type: object
      properties:
        code:
          type: string
          description: The procedure code that was queried.
          example: '90837'
        npi_count:
          type: integer
          description: Number of distinct NPIs in the distribution.
          example: 1128940
        ein_count:
          type: integer
          description: Number of distinct EINs in the distribution.
          example: 270301
        weighting:
          type: string
          description: Weighting method applied to the distribution.
          example: ein
        distribution:
          $ref: '#/components/schemas/Percentiles'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Serif Health API key passed as a Bearer token in the Authorization header (Authorization: Bearer <API_KEY>). API keys are issued by Serif Health; contact hello@serifhealth.com for access.'