openapi: 3.0.1
info:
  title: Payerset Data Lake API
  description: >-
    The Payerset Data Lake API provides programmatic access to U.S. healthcare
    price transparency data parsed from payer Transparency in Coverage (TiC)
    machine-readable files and hospital price transparency MRFs, enriched with
    provider, payer, and billing-code reference metadata. Endpoints support
    payer/provider negotiated rate lookups, NPI and TIN provider mapping,
    billing-code classification, and hospital MRF discovery. Authentication is
    via an API key supplied in the x-api-key header.
  contact:
    name: Payerset Support
    email: support@payerset.com
    url: https://www.payerset.com
  version: '2024-10-31'
servers:
  - url: https://api.payerset.com
    description: Payerset Data Lake production API
security:
  - api_key: []
tags:
  - name: Rates
    description: Payer-provider negotiated rate lookups from Transparency in Coverage MRFs.
  - name: Payers
    description: Payer reference metadata and payer listings.
  - name: Providers
    description: Provider (NPI), organization, and tax identification (TIN) reference metadata and mappings.
  - name: Billing Codes
    description: Billing code classification, categorization, and code type reference data.
  - name: Hospital MRF
    description: Hospital price transparency machine-readable file discovery (hospitals, systems, payers).
paths:
  /v1/rates/rate_query:
    get:
      operationId: queryRate
      tags:
        - Rates
      summary: Query negotiated rate
      description: >-
        Returns the negotiated rate(s) for a given combination of billing code,
        payer, and provider NPI, derived from payer Transparency in Coverage
        machine-readable files.
      parameters:
        - name: billing_code
          in: query
          required: true
          description: Service billing code (e.g., CPT/HCPCS/MS-DRG such as "27447").
          schema:
            type: string
        - name: payer
          in: query
          required: true
          description: Payer system name (e.g., "Aetna").
          schema:
            type: string
        - name: npi
          in: query
          required: true
          description: National Provider Identifier of the provider.
          schema:
            type: string
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rateQuery'
      security:
        - api_key: []
  /v1/metadata/payers/payer_detail:
    get:
      operationId: getPayerDetail
      tags:
        - Payers
      summary: Get payer detail
      description: Returns descriptive metadata for payers, including region, category, friendly name, and system name.
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payerDetail'
      security:
        - api_key: []
  /v1/metadata/payers/payer_list:
    get:
      operationId: getPayerList
      tags:
        - Payers
      summary: Get payer list
      description: Returns the list of payer system names available in the Data Lake.
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payerList'
      security:
        - api_key: []
  /v1/metadata/providers/npi_detail:
    get:
      operationId: getNpiDetail
      tags:
        - Providers
      summary: Get NPI detail
      description: >-
        Returns enriched provider metadata for a given NPI, including NPPES
        organization details, location, taxonomy classification, EIN, and
        Medicare enrollment information.
      parameters:
        - name: npi
          in: query
          required: true
          description: National Provider Identifier (e.g., "1234567890").
          schema:
            type: string
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/npiDetail'
      security:
        - api_key: []
  /v1/metadata/providers/npi_to_tin:
    get:
      operationId: getNpiToTin
      tags:
        - Providers
      summary: Get NPI to TIN mapping
      description: Returns the tax identification number(s) (TIN) associated with provider NPIs.
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/npiToTin'
      security:
        - api_key: []
  /v1/metadata/providers/tin_to_npi:
    get:
      operationId: getTinToNpi
      tags:
        - Providers
      summary: Get TIN to NPI mapping
      description: Returns the provider NPI(s) associated with a given tax identification number (TIN).
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tinToNpi'
      security:
        - api_key: []
  /v1/metadata/providers/npi_to_parent:
    get:
      operationId: getNpiToParent
      tags:
        - Providers
      summary: Get NPI to parent mapping
      description: Returns the parent organization NPI and TIN associated with provider NPIs.
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/npiToParent'
      security:
        - api_key: []
  /v1/metadata/providers/npi_parent:
    get:
      operationId: getNpiParent
      tags:
        - Providers
      summary: Get NPI parent
      description: Returns parent organization NPI relationships for providers.
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/npiParent'
      security:
        - api_key: []
  /v1/metadata/billing_codes/code_detail:
    get:
      operationId: getBillingCodeDetail
      tags:
        - Billing Codes
      summary: Get billing code detail
      description: >-
        Returns metadata for a specific billing code, including code type,
        name, category, and subcategory classification.
      parameters:
        - name: billing_code
          in: query
          required: true
          description: Billing code to look up (e.g., "99213").
          schema:
            type: string
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/billingCode'
      security:
        - api_key: []
  /v1/metadata/billing_codes/code_types:
    get:
      operationId: getBillingCodeTypes
      tags:
        - Billing Codes
      summary: Get billing code types
      description: Returns the list of supported billing code types (e.g., CPT, HCPCS, MS-DRG).
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codeType'
  /v1/hospital_mrf/hospital_list:
    get:
      operationId: getHospitalList
      tags:
        - Hospital MRF
      summary: Get hospital list
      description: Returns the list of hospitals with published price transparency machine-readable files.
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/hospitalList'
      security:
        - api_key: []
  /v1/hospital_mrf/system_list:
    get:
      operationId: getSystemList
      tags:
        - Hospital MRF
      summary: Get system list
      description: Returns the list of hospital systems represented in the hospital MRF dataset.
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/systemList'
      security:
        - api_key: []
  /v1/hospital_mrf/payer_list:
    get:
      operationId: getHospitalPayerList
      tags:
        - Hospital MRF
      summary: Get hospital payer list
      description: Returns the list of payers present in the hospital price transparency MRF dataset.
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/hospitalPayerList'
      security:
        - api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
  schemas:
    rateQuery:
      type: object
      description: >-
        Negotiated rate query result. The published API definition references a
        generic object schema for this response; fields are not enumerated in
        the provider's machine-readable definition.
      additionalProperties: true
    payerDetail:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              payer_region:
                type: string
              payer_category:
                type: string
              payer_friendly_name:
                type: string
              payer_system_name:
                type: string
    payerList:
      required:
        - payers
      type: object
      properties:
        payers:
          type: array
          items:
            type: string
    npiDetail:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              npi:
                type: string
              taxonomygrouping:
                type: string
              taxonomyclassification:
                type: string
              taxonomyspecialization:
                type: string
              taxonomydisplayname:
                type: string
              organizationname:
                type: string
              state:
                type: string
              city:
                type: string
              zip:
                type: string
              primarytaxonomycode:
                type: string
              orgfriendlyname:
                type: string
              county:
                type: string
              ein:
                type: string
              latitude:
                type: string
              longitude:
                type: string
              medicare_enrollment_id:
                type: string
              medicare_enrollment_specialty:
                type: string
    npiToTin:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              npi:
                type: string
              tin_value:
                type: string
    tinToNpi:
      type: object
      properties:
        count:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              npi:
                type: string
              tin_value:
                type: string
    npiToParent:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              npi:
                type: string
              npi_parent:
                type: string
              tin_value:
                type: string
    npiParent:
      type: object
      properties:
        count:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              npi_parent:
                type: string
              npi:
                type: string
    billingCode:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              billing_code:
                type: string
              name:
                type: string
              code_type:
                type: string
              category:
                type: string
              subcategory:
                type: string
    codeType:
      required:
        - code_types
      type: object
      properties:
        code_types:
          type: array
          items:
            type: string
    hospitalList:
      required:
        - Count
        - Items
      type: object
      properties:
        Count:
          type: integer
        Items:
          type: array
          items:
            required:
              - hospital_id
              - hospital_name
              - system_name
            type: object
            properties:
              system_name:
                type: string
              hospital_id:
                type: string
              hospital_name:
                type: string
    systemList:
      required:
        - Count
        - Items
      type: object
      properties:
        Count:
          type: integer
        Items:
          type: array
          items:
            required:
              - state
              - system_id
              - system_name
            type: object
            properties:
              system_id:
                type: string
              system_name:
                type: string
              state:
                type: string
    hospitalPayerList:
      required:
        - Count
        - Items
      type: object
      properties:
        Count:
          type: integer
        Items:
          type: array
          items:
            required:
              - payer_id
              - payer_name
              - payer_type
              - state
            type: object
            properties:
              payer_id:
                type: string
              payer_name:
                type: string
              payer_type:
                type: string
              state:
                type: string