> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rcintell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculate claim-scoped payment

> Compose payment for a whole claim: ``lines[]`` plus ``dx[]`` at a CCN.

Each line runs the same four-block composer as ``GET /v1/codes/{code}/payment``.
OPPS status-indicator packaging (N / Q1 / Q2 / J1) and T-status 50%
multiple-procedure reduction are applied across the claim. NCCI PTP is
checked on unique codes; MUE is compared to summed units per code. LCD
covered DX (when loaded) is matched against ``dx``.



## OpenAPI

````yaml /docs/openapi.client.json post /v1/knowledge/payment-calc/claim
openapi: 3.1.0
info:
  description: >-
    Client API for RCIntel. Admin ingest, catalog sync, and internal audit
    routes are omitted. See Guides → Which API to use.
  summary: Multi-tenant knowledge API for healthcare revenue cycle management.
  title: Healthcare Knowledge Layer
  version: 0.1.0
servers: []
security: []
tags:
  - description: >-
      Geographic payer policy lookup (national NCD vs MAC LCD vs state). Query
      payer, code, state, plan_type. Each row includes geo_scope and
      document_version.
    name: policies
  - description: >-
      Payer network directory — search payers, check prior auth requirements,
      view filing rules, denial patterns, and appeal levels.
    name: payers
  - description: >-
      Resolve healthcare billing knowledge across the L1-L6 layer stack.
      Includes payment calculation, billing guidance, and per-layer queries.
    name: knowledge
  - description: >-
      CMS Fee Schedule lookups — OPPS (Addendum B / APC), DMEPOS (state-level
      pricing), and Clinical Lab Fee Schedule (CLFS).
    name: fee-schedules
  - description: >-
      NCCI (National Correct Coding Initiative) — dedicated MUE limits, PTP
      bundling edits, add-on code edits, and code pair validation.
    name: ncci
  - description: >-
      Service code intelligence — CPT/HCPCS lookup, RVU data, NCCI edits,
      payment calculation, implant/GUDID search, and service group
      classification.
    name: codes
  - description: >-
      Submit asynchronous AI agent jobs for code research, medical necessity,
      and denial resolution. Poll for results and retrieve reasoning traces.
    name: agents
  - description: >-
      Register and manage healthcare facilities by CCN (Medicare Provider
      Number). Each facility is the root entity for knowledge resolution.
    name: facilities
  - description: >-
      NPI Registry — live search against CMS NPPES API for provider and
      organization National Provider Identifiers.
    name: npi
  - description: >-
      OpenFDA drug product lookup by NDC. Includes product-level fields with
      normalized ingredient and package detail.
    name: drugs
  - description: Health checks, service metadata, and Prometheus metrics.
    name: system
paths:
  /v1/knowledge/payment-calc/claim:
    post:
      tags:
        - knowledge
      summary: Calculate claim-scoped payment
      description: >-
        Compose payment for a whole claim: ``lines[]`` plus ``dx[]`` at a CCN.


        Each line runs the same four-block composer as ``GET
        /v1/codes/{code}/payment``.

        OPPS status-indicator packaging (N / Q1 / Q2 / J1) and T-status 50%

        multiple-procedure reduction are applied across the claim. NCCI PTP is

        checked on unique codes; MUE is compared to summed units per code. LCD

        covered DX (when loaded) is matched against ``dx``.
      operationId: payment_calc_claim_v1_knowledge_payment_calc_claim_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentClaimRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentClaimResponse'
          description: Per-line allowed amounts, OPPS packaging, NCCI, DX coverage
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - APIKeyHeader: []
components:
  schemas:
    PaymentClaimRequest:
      description: 'Claim-scoped payment composition: many lines + a DX list at one CCN.'
      examples:
        - ccn: '170001'
          dx:
            - M17.11
            - E11.9
          lines:
            - code: '99213'
              units: 1
            - code: '36415'
              units: 1
      properties:
        ccn:
          description: 6-digit Medicare Provider Number
          pattern: ^\d{6}$
          title: Ccn
          type: string
        date_of_service:
          anyOf:
            - type: string
            - type: 'null'
          description: YYYY-MM-DD for NCCI/MUE versioning
          title: Date Of Service
        dx:
          description: ICD-10-CM diagnosis codes
          items:
            type: string
          title: Dx
          type: array
        lines:
          items:
            $ref: '#/components/schemas/PaymentClaimLine'
          maxItems: 25
          minItems: 1
          title: Lines
          type: array
        payer:
          anyOf:
            - type: string
            - type: 'null'
          description: Payer name (unused by fee-schedule math)
          title: Payer
        place_of_service:
          anyOf:
            - type: string
            - type: 'null'
          description: Claim-level POS default
          title: Place Of Service
        qpp:
          default: true
          description: Use QPP conversion factor
          title: Qpp
          type: boolean
      required:
        - ccn
        - lines
      title: PaymentClaimRequest
      type: object
    PaymentClaimResponse:
      description: 'Claim rollup: per-line allowed, OPPS packaging, NCCI, DX coverage.'
      properties:
        applicable_blocks:
          items:
            type: string
          title: Applicable Blocks
          type: array
        ccn:
          title: Ccn
          type: string
        coverage:
          items:
            $ref: '#/components/schemas/PaymentClaimCoverage'
          title: Coverage
          type: array
        dx:
          items:
            type: string
          title: Dx
          type: array
        lines:
          items:
            $ref: '#/components/schemas/PaymentClaimLineResult'
          title: Lines
          type: array
        methodology:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology
        ncci_clean:
          default: true
          title: Ncci Clean
          type: boolean
        ncci_conflicts:
          items:
            $ref: '#/components/schemas/NCCIBatchConflict'
          title: Ncci Conflicts
          type: array
        policy_rules:
          items:
            $ref: '#/components/schemas/PolicyRuleResponse'
          title: Policy Rules
          type: array
        reliability:
          $ref: '#/components/schemas/ReliabilityMetadata'
        totals:
          $ref: '#/components/schemas/PaymentClaimTotals'
      required:
        - ccn
        - lines
        - totals
      title: PaymentClaimResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    PaymentClaimLine:
      description: >-
        One procedure line on a claim — shared by payment-calc/claim and
        resolve.
      properties:
        code:
          maxLength: 5
          minLength: 5
          pattern: ^[A-Za-z0-9]{5}$
          title: Code
          type: string
        line_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Client line id; defaults to 1-based index
          title: Line Id
        modifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Modifier
        place_of_service:
          anyOf:
            - type: string
            - type: 'null'
          description: POS override for this line
          title: Place Of Service
        units:
          default: 1
          maximum: 999
          minimum: 1
          title: Units
          type: integer
      required:
        - code
      title: PaymentClaimLine
      type: object
    PaymentClaimCoverage:
      description: LCD/NCD vs claim DX for one procedure code.
      properties:
        code:
          title: Code
          type: string
        coverage_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Coverage Status
        dx_required:
          default: false
          title: Dx Required
          type: boolean
        lcd_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Lcd Id
        matched_dx:
          items:
            type: string
          title: Matched Dx
          type: array
        ncd_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Ncd Id
        source_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Url
      required:
        - code
      title: PaymentClaimCoverage
      type: object
    PaymentClaimLineResult:
      description: Per-line composition plus claim-level OPPS/MUE adjustments.
      properties:
        code:
          title: Code
          type: string
        dme_allowed:
          anyOf:
            - type: number
            - type: 'null'
          title: Dme Allowed
        facility_allowed:
          anyOf:
            - type: number
            - type: 'null'
          title: Facility Allowed
        found:
          default: true
          title: Found
          type: boolean
        lab_allowed:
          anyOf:
            - type: number
            - type: 'null'
          title: Lab Allowed
        line_id:
          title: Line Id
          type: string
        modifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Modifier
        mue_exceeded:
          default: false
          title: Mue Exceeded
          type: boolean
        mue_value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Mue Value
        multiple_procedure_discount:
          default: 1
          title: Multiple Procedure Discount
          type: number
        notes:
          items:
            type: string
          title: Notes
          type: array
        opps_status_indicator:
          anyOf:
            - type: string
            - type: 'null'
          title: Opps Status Indicator
        packaged:
          default: false
          title: Packaged
          type: boolean
        payment:
          anyOf:
            - $ref: '#/components/schemas/CodePaymentResponse'
            - type: 'null'
        physician_allowed:
          anyOf:
            - type: number
            - type: 'null'
          title: Physician Allowed
        units:
          default: 1
          title: Units
          type: integer
      required:
        - line_id
        - code
      title: PaymentClaimLineResult
      type: object
    NCCIBatchConflict:
      description: A single PTP conflict found within the batch.
      properties:
        claim_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Claim Type
        code1:
          title: Code1
          type: string
        code2:
          title: Code2
          type: string
        col1_proc_cd:
          anyOf:
            - type: string
            - type: 'null'
          title: Col1 Proc Cd
        col2_proc_cd:
          anyOf:
            - type: string
            - type: 'null'
          title: Col2 Proc Cd
        effective_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Effective Date
        is_bundled:
          default: true
          title: Is Bundled
          type: boolean
        modifier_allowed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Modifier Allowed
        modifier_indicator:
          anyOf:
            - type: string
            - type: 'null'
          title: Modifier Indicator
        ptp_rationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Ptp Rationale
      required:
        - code1
        - code2
      title: NCCIBatchConflict
      type: object
    PolicyRuleResponse:
      description: Policy-rule evidence extracted from CMS transmittals and linked by code.
      properties:
        action:
          anyOf:
            - type: string
            - type: 'null'
          title: Action
        change_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Change Type
        code:
          title: Code
          type: string
        discovery_depth:
          default: 0
          title: Discovery Depth
          type: integer
        doc_id:
          title: Doc Id
          type: string
        effective_from:
          anyOf:
            - type: string
            - type: 'null'
          title: Effective From
        kind:
          title: Kind
          type: string
        license_kind:
          default: public
          title: License Kind
          type: string
        lineage_root_doc_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Lineage Root Doc Id
        parent_doc_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Doc Id
        pdf_uri:
          title: Pdf Uri
          type: string
        rule_text:
          title: Rule Text
          type: string
        source_key:
          title: Source Key
          type: string
        trigger_condition:
          anyOf:
            - type: string
            - type: 'null'
          title: Trigger Condition
      required:
        - code
        - source_key
        - doc_id
        - pdf_uri
        - kind
        - rule_text
      title: PolicyRuleResponse
      type: object
    ReliabilityMetadata:
      description: User-visible reliability metadata attached to API responses.
      properties:
        data_sources:
          additionalProperties:
            type: string
          description: Data-source backends used to build this response.
          title: Data Sources
          type: object
        dataset_versions:
          additionalProperties:
            type: string
          description: >-
            CMS/DHCS/NLM/FDA named versions used to compose this response (e.g.
            mpfs=CY2026, ipps=FY2026). See GET /v1/data/changes.
          title: Dataset Versions
          type: object
        degraded:
          default: false
          description: True when a fallback or non-primary source path was used.
          title: Degraded
          type: boolean
        generated_at:
          description: UTC timestamp when the response payload was composed.
          title: Generated At
          type: string
        warnings:
          description: Human-readable caveats relevant to downstream consumers.
          items:
            type: string
          title: Warnings
          type: array
      required:
        - generated_at
      title: ReliabilityMetadata
      type: object
    PaymentClaimTotals:
      properties:
        dme:
          default: 0
          title: Dme
          type: number
        lab:
          default: 0
          title: Lab
          type: number
        outpatient_facility:
          default: 0
          title: Outpatient Facility
          type: number
        physician:
          default: 0
          title: Physician
          type: number
      title: PaymentClaimTotals
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    CodePaymentResponse:
      description: >-
        Multi-block payment composition for a HCPCS / CPT code at a facility.


        When ``ccn`` is provided, the response is composed against the
        facility's

        geography (LOCCO → GPCI, CBSA → wage_index). When omitted, only the

        ``physician`` block is populated using the supplied ``locality`` query

        param (legacy GPCI-only behavior).


        ``applicable_blocks`` lists which sub-blocks have data — drives display

        on the consuming UI.
      properties:
        applicable_blocks:
          items:
            type: string
          title: Applicable Blocks
          type: array
        ccn:
          anyOf:
            - type: string
            - type: 'null'
          title: Ccn
        code:
          title: Code
          type: string
        conversion_factor:
          title: Conversion Factor
          type: number
        date_of_service:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Of Service
        dme:
          anyOf:
            - $ref: '#/components/schemas/DMEPaymentBlock'
            - type: 'null'
        estimated_payment:
          anyOf:
            - type: number
            - type: 'null'
          title: Estimated Payment
        facility:
          anyOf:
            - $ref: '#/components/schemas/FacilityContextBlock'
            - type: 'null'
        facility_rate:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Facility Rate
        lab:
          anyOf:
            - $ref: '#/components/schemas/LabPaymentBlock'
            - type: 'null'
        locality:
          anyOf:
            - type: string
            - type: 'null'
          title: Locality
        mp_gpci:
          anyOf:
            - type: number
            - type: 'null'
          title: Mp Gpci
        mp_rvu_adjusted:
          anyOf:
            - type: number
            - type: 'null'
          title: Mp Rvu Adjusted
        outpatient_facility:
          anyOf:
            - $ref: '#/components/schemas/FacilityPaymentBlock'
            - type: 'null'
        pe_gpci:
          anyOf:
            - type: number
            - type: 'null'
          title: Pe Gpci
        pe_rvu_adjusted:
          anyOf:
            - type: number
            - type: 'null'
          title: Pe Rvu Adjusted
        physician:
          anyOf:
            - $ref: '#/components/schemas/PhysicianPaymentBlock'
            - type: 'null'
        policy_rules:
          items:
            $ref: '#/components/schemas/PolicyRuleResponse'
          title: Policy Rules
          type: array
        pw_gpci:
          anyOf:
            - type: number
            - type: 'null'
          title: Pw Gpci
        qpp:
          default: true
          description: QPP-participating conversion factor used
          title: Qpp
          type: boolean
        reliability:
          $ref: '#/components/schemas/ReliabilityMetadata'
          description: User-visible reliability metadata for this payment composition.
        total_adjusted_rvu:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Adjusted Rvu
        work_rvu_adjusted:
          anyOf:
            - type: number
            - type: 'null'
          title: Work Rvu Adjusted
      required:
        - code
        - conversion_factor
      title: CodePaymentResponse
      type: object
    DMEPaymentBlock:
      description: DMEPOS payment — picks rural vs non-rural rate by facility flag.
      properties:
        allowed_dme_payment:
          title: Allowed Dme Payment
          type: number
        dme_payment_rate:
          title: Dme Payment Rate
          type: number
        is_rural:
          default: false
          title: Is Rural
          type: boolean
        rate_used:
          default: non_rural
          description: '''rural'' or ''non_rural'''
          title: Rate Used
          type: string
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
      required:
        - dme_payment_rate
        - allowed_dme_payment
      title: DMEPaymentBlock
      type: object
    FacilityContextBlock:
      description: Facility context used to drive payment composition.
      properties:
        cbsa:
          anyOf:
            - type: string
            - type: 'null'
          title: Cbsa
        ccn:
          title: Ccn
          type: string
        county:
          anyOf:
            - type: string
            - type: 'null'
          title: County
        facility_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Facility Type
        is_rural:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Rural
        locality_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Locality Name
        locality_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Locality Number
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        pos_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Pos Code
        registered:
          default: true
          description: >-
            True when geography came from a facility registered to the tenant
            (county-precise locality + CBSA wage index). False when it was
            derived from the raw CCN (state-level 'Rest of State' locality; no
            CBSA wage index).
          title: Registered
          type: boolean
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        wage_index:
          anyOf:
            - type: number
            - type: 'null'
          title: Wage Index
      required:
        - ccn
      title: FacilityContextBlock
      type: object
    LabPaymentBlock:
      description: >-
        Clinical Lab Fee Schedule payment (national rate, no geographic
        adjustment).
      properties:
        allowed_lab_payment:
          title: Allowed Lab Payment
          type: number
        indicator:
          anyOf:
            - type: string
            - type: 'null'
          title: Indicator
        lab_payment_rate:
          title: Lab Payment Rate
          type: number
      required:
        - lab_payment_rate
        - allowed_lab_payment
      title: LabPaymentBlock
      type: object
    FacilityPaymentBlock:
      description: |-
        OPPS / outpatient hospital facility payment block.

        payment = (rate * 0.6 * wage_index) + (rate * 0.4)
      properties:
        allowed_fac_payment:
          title: Allowed Fac Payment
          type: number
        apc_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Apc Code
        labor_share:
          default: 0.6
          title: Labor Share
          type: number
        non_labor_share:
          default: 0.4
          title: Non Labor Share
          type: number
        opps_payment_rate:
          title: Opps Payment Rate
          type: number
        relative_weight:
          anyOf:
            - type: number
            - type: 'null'
          title: Relative Weight
        status_indicator:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Indicator
        wage_index:
          default: 1
          title: Wage Index
          type: number
      required:
        - opps_payment_rate
        - allowed_fac_payment
      title: FacilityPaymentBlock
      type: object
    PhysicianPaymentBlock:
      description: >-
        MPFS payment block — work + PE + MP, GPCI-adjusted, then * conversion
        factor.
      properties:
        allowed_phy_payment:
          title: Allowed Phy Payment
          type: number
        conversion_factor:
          title: Conversion Factor
          type: number
        mp_gpci:
          title: Mp Gpci
          type: number
        mp_rvu:
          title: Mp Rvu
          type: number
        mp_rvu_adjusted:
          title: Mp Rvu Adjusted
          type: number
        pe_gpci:
          title: Pe Gpci
          type: number
        pe_rvu:
          description: fac_pe_rvu when facility, otherwise non_fac_pe_rvu
          title: Pe Rvu
          type: number
        pe_rvu_adjusted:
          title: Pe Rvu Adjusted
          type: number
        pe_rvu_source:
          default: facility
          description: 'Which PE RVU was used: ''facility'' or ''non_facility'''
          title: Pe Rvu Source
          type: string
        pw_gpci:
          title: Pw Gpci
          type: number
        rvu_quarter:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            CMS fee-schedule quarter (1-4) of the RVU row used, when the source
            tracks quarters.
          title: Rvu Quarter
        rvu_source:
          default: postgres
          description: >-
            Backend the RVUs were read from: 'postgres' (legacy seed) or
            'clickhouse' (mart_fee_schedule).
          title: Rvu Source
          type: string
        rvu_year:
          anyOf:
            - type: integer
            - type: 'null'
          description: CMS fee-schedule year of the RVU row used for this calculation.
          title: Rvu Year
        total_adjusted_rvu:
          title: Total Adjusted Rvu
          type: number
        work_rvu:
          title: Work Rvu
          type: number
        work_rvu_adjusted:
          title: Work Rvu Adjusted
          type: number
      required:
        - pw_gpci
        - pe_gpci
        - mp_gpci
        - work_rvu
        - pe_rvu
        - mp_rvu
        - work_rvu_adjusted
        - pe_rvu_adjusted
        - mp_rvu_adjusted
        - total_adjusted_rvu
        - conversion_factor
        - allowed_phy_payment
      title: PhysicianPaymentBlock
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey

````