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

# Get in-network contracted rates

> Retrieve contracted rates for healthcare providers (NPIs) for specific billing codes and insurance plans. 

This endpoint supports bulk lookups for up to **50 NPIs** per request, enabling efficient pricing 
discovery across multiple providers simultaneously.

### Supported Rate Types
- **Fee-for-Service (FFS)** – Per-procedure contracted rates
- **Capitated** – Monthly per-member rates *(coming soon)*
- **Bundled** – Episode-based payment models *(coming soon)*

### Use Cases
- Care navigation and provider comparison
- Patient cost estimation and transparency
- Network adequacy analysis
- Provider directory integration
- Contracting and compliance analysis




## OpenAPI

````yaml openapi.yml post /pricing/in-network
openapi: 3.1.1
info:
  title: Care Navigation Data API
  version: 1.0.0
  description: >
    # Care Navigation Data API


    The **Care Navigation Data API** provides pricing transparency and provider
    capability data to support informed care navigation, contracting & comliance
    decisions. 

    Our data platform delivers monthly-refreshed contracted rates and procedure
    likelihood scores.



    ## Key Features


    🏥 **In-Network Pricing** – Access contracted rates for healthcare providers
    across multiple billing codes and insurance plans, mined from Terabytes of
    MRF data  

    📊 **Procedure Likelihood** – Get confidence scores indicating provider
    capability for specific medical services & procedures  

    ⚡ **Latest Data** – Monthly-refreshed data with 99.9% uptime SLA



    ## Getting Started


    1. **Contact us** at support@docaroo.com to request API access and receive
    your sandbox API key

    2. **Authenticate** by including your API key in the `X-API-Key` header with
    every request

    3. **Test** using our interactive documentation below or make your first API
    call


    ### Quick Example


    ```bash

    curl -X POST
    "https://care-navigation-gateway-ccg16t89.wl.gateway.dev/pricing/in-network?key=your-api-key-here"
    \
      -H "Content-Type: application/json" \
      -d '{
        "npis": ["1234567890"],
        "planId": "940360524",
        "conditionCode": "99214",
        "codeType": "CPT"
      }'
    ```


    ---
servers:
  - url: https://care-navigation-gateway-ccg16t89.wl.gateway.dev
    description: API Gateway (deployed)
  - url: https://sandbox.api.docaroo.com/v1
    description: Sandbox environment for testing and development
  - url: https://api.docaroo.com/v1
    description: Production environment (coming soon)
security:
  - apiKeyAuth: []
tags:
  - name: Pricing
    description: In-network contracted rate lookup and pricing transparency
  - name: Procedure Likelihood
    description: Provider capability assessment and procedure likelihood scoring
paths:
  /pricing/in-network:
    post:
      tags:
        - Pricing
      summary: Get in-network contracted rates
      description: >
        Retrieve contracted rates for healthcare providers (NPIs) for specific
        billing codes and insurance plans. 


        This endpoint supports bulk lookups for up to **50 NPIs** per request,
        enabling efficient pricing 

        discovery across multiple providers simultaneously.


        ### Supported Rate Types

        - **Fee-for-Service (FFS)** – Per-procedure contracted rates

        - **Capitated** – Monthly per-member rates *(coming soon)*

        - **Bundled** – Episode-based payment models *(coming soon)*


        ### Use Cases

        - Care navigation and provider comparison

        - Patient cost estimation and transparency

        - Network adequacy analysis

        - Provider directory integration

        - Contracting and compliance analysis
      operationId: getInNetworkPricing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InNetworkPricingRequest'
            examples:
              basicRequest:
                summary: Basic pricing lookup
                description: Simple request for some providers and a CPT code
                value:
                  npis:
                    - '1043566623'
                    - '1972767655'
                  planId: '942404110'
                  conditionCode: '99214'
                  codeType: CPT
      responses:
        '200':
          $ref: '#/components/responses/InNetworkPricingSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    InNetworkPricingRequest:
      type: object
      required:
        - npis
        - conditionCode
      properties:
        npis:
          type: array
          minItems: 1
          maxItems: 50
          description: List of National Provider Identifiers (NPIs) to lookup pricing for
          items:
            type: string
            pattern: ^[0-9]{10}$
            description: 10-digit National Provider Identifier
          example:
            - '1043566623'
            - '1972767655'
        planId:
          type: string
          default: '942404110'
          description: >
            Insurance plan identifier. Accepts:

            - **EIN** (Employer Identification Number) for self-funded plans

            - **HIOS ID** (Health Insurance Oversight System) for marketplace
            plans

            - **Custom Plan ID** for proprietary plan identification
          example: '942404110'
        conditionCode:
          type: string
          description: Medical billing code to retrieve pricing for
          example: '99214'
        codeType:
          $ref: '#/components/schemas/CodeType'
    CodeType:
      type: string
      enum:
        - CPT
        - NDC
        - HCPCS
        - RC
        - ICD
        - MS-DRG
        - R-DRG
        - S-DRG
        - APS-DRG
        - AP-DRG
        - APR-DRG
        - APC
        - LOCAL
        - EAPG
        - HIPPS
        - CDT
        - CSTM-ALL
      default: CPT
      description: |
        Medical billing code standard:
        - **CPT**: Current Procedural Terminology
        - **NDC**: National Drug Code
        - **HCPCS**: Healthcare Common Procedure Coding System
        - **ICD**: International Classification of Diseases
        - **DRG**: Diagnosis Related Group (various types)
        - **APC**: Ambulatory Payment Classification
        - **CDT**: Current Dental Terminology
      example: CPT
    InNetworkPricingResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: object
          description: >-
            Pricing data organized by NPI, with each NPI containing an array of
            rate objects grouped by negotiated type
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/InNetworkPrice'
        meta:
          $ref: '#/components/schemas/PricingResponseMeta'
    ErrorResponse:
      type: object
      required:
        - type
        - title
        - status
        - detail
      properties:
        type:
          type: string
          format: uri
          description: URI reference identifying the problem type
          example: https://docs.docaroo.com/errors/bad-request
        title:
          type: string
          description: Short, human-readable summary of the problem
          example: Bad Request
        status:
          type: integer
          format: int32
          description: HTTP status code
          example: 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
          example: The planId parameter is required but was not provided.
        instance:
          type: string
          format: uri
          description: URI reference identifying the specific occurrence
          example: /pricing/in-network
        requestId:
          type: string
          description: Unique request identifier for debugging
          example: req_error123
        timestamp:
          type: string
          format: date-time
          description: When the error occurred
          example: '2024-01-15T14:30:00Z'
    ValidationErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - field
              - message
            properties:
              field:
                type: string
                description: The field that caused the validation error
              message:
                type: string
                description: A human-readable message explaining the validation error
    InNetworkPrice:
      type: object
      required:
        - code
        - codeType
        - negotiatedPrices
        - summary
      properties:
        code:
          type: string
          description: The billing code that was requested
          example: '99214'
        codeType:
          $ref: '#/components/schemas/CodeType'
        negotiatedPrices:
          type: array
          items:
            $ref: '#/components/schemas/NegotiatedPriceDetail'
          description: Array of individual negotiated price details
        summary:
          $ref: '#/components/schemas/PricingSummary'
          description: Summary statistics for all negotiated rates
    PricingResponseMeta:
      type: object
      required:
        - planId
        - requestId
        - timestamp
        - payer
        - processingTimeMs
        - inNetworkRecordsCount
      properties:
        planId:
          type: string
          description: The insurance plan ID that was queried
          example: '940360524'
        planName:
          type: string
          description: The insurance plan name corresponding to the plan ID
          example: UHC Choice Plus POS
        payer:
          $ref: '#/components/schemas/PayerEnum'
        requestId:
          type: string
          description: Unique identifier for this request (useful for support)
          example: req_abc123def456
        timestamp:
          type: string
          format: date-time
          description: When this response was generated
          example: '2024-01-15T14:30:00Z'
        processingTimeMs:
          type: integer
          description: Processing time in milliseconds
          example: 245
        inNetworkRecordsCount:
          type: integer
          description: Total number of in-network records found
          example: 42
    NegotiatedPriceDetail:
      type: object
      required:
        - negotiatedRate
        - negotiatedType
      properties:
        negotiatedRate:
          type: number
          format: float
          minimum: 0
          description: Individual negotiated rate amount
          example: 128.8
        expirationDate:
          type: string
          format: date
          nullable: true
          description: |
            Date when this negotiated rate expires (ISO 8601 format).
            Null if no expiration date specified.
          example: '2024-12-31'
        serviceCodes:
          type: array
          items:
            type: string
            pattern: ^[0-9]{2}$
          description: >
            Array of two-digit CMS Place of Service codes that identify where
            medical services are provided.

            Common codes include: 11 (Office), 21 (Inpatient Hospital), 22
            (Outpatient Hospital), 23 (Emergency Room).
          example:
            - '11'
            - '22'
        billingClass:
          type: string
          nullable: true
          description: |
            Billing class or classification for this rate.
            Null if not specified.
          example: professional
        negotiatedType:
          $ref: '#/components/schemas/NegotiatedType'
        tinType:
          type: string
          nullable: true
          description: |
            Tax Identification Number type (e.g., "EIN", "SSN").
            Null if not specified.
          example: EIN
        tinValue:
          type: string
          nullable: true
          description: |
            Tax Identification Number value.
            Null if not specified.
          example: '123456789'
    PricingSummary:
      type: object
      required:
        - minRate
        - maxRate
        - avgRate
        - instances
      properties:
        minRate:
          type: number
          format: float
          minimum: 0
          description: Minimum negotiated rate amount found
          example: 128.8
        maxRate:
          type: number
          format: float
          minimum: 0
          description: Maximum negotiated rate amount found
          example: 151.53
        avgRate:
          type: number
          format: float
          minimum: 0
          description: Average negotiated rate amount
          example: 140.16
        instances:
          type: integer
          minimum: 0
          description: Number of negotiated rate records found
          example: 5
    PayerEnum:
      type: string
      enum:
        - UNH
      description: >
        Supported insurance payers.

        Only United Health (UNH) supported for now. More networks are actively
        being added.


        - **UNH**: United Health
      example: UNH
    NegotiatedType:
      type: string
      enum:
        - negotiated
        - derived
        - fee_schedule
        - percentage
        - per_diem
      description: |
        Nature of the rate:
        - **negotiated**: Contractually agreed dollar amount
        - **derived**: Internally calculated rate
        - **fee_schedule**: Published fee schedule rate
        - **percentage**: Percentage of billed charges
        - **per_diem**: Daily rate (e.g., room & board)
      example: negotiated
  responses:
    InNetworkPricingSuccess:
      description: Successful pricing lookup
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InNetworkPricingResponse'
          examples:
            multipleProviders:
              summary: Multiple provider pricing
              description: Pricing data for multiple providers with different rate types
              value:
                data:
                  '1043566623':
                    - code: '99214'
                      codeType: CPT
                      negotiatedPrices:
                        - negotiatedRate: 65.87
                          expirationDate: '2024-12-31'
                          serviceCodes:
                            - '11'
                          billingClass: professional
                          negotiatedType: negotiated
                          tinType: EIN
                          tinValue: '123456789'
                        - negotiatedRate: 128.45
                          expirationDate: '2024-12-31'
                          serviceCodes:
                            - '11'
                          billingClass: professional
                          negotiatedType: negotiated
                          tinType: EIN
                          tinValue: '123456789'
                        - negotiatedRate: 142.1
                          expirationDate: null
                          serviceCodes: []
                          billingClass: null
                          negotiatedType: negotiated
                          tinType: null
                          tinValue: null
                        - negotiatedRate: 189.5
                          expirationDate: '2024-12-31'
                          serviceCodes:
                            - '22'
                          billingClass: professional
                          negotiatedType: negotiated
                          tinType: EIN
                          tinValue: '987654321'
                        - negotiatedRate: 213.75
                          expirationDate: null
                          serviceCodes: []
                          billingClass: null
                          negotiatedType: negotiated
                          tinType: null
                          tinValue: null
                        - negotiatedRate: 266.88
                          expirationDate: '2024-12-31'
                          serviceCodes:
                            - '11'
                          billingClass: professional
                          negotiatedType: negotiated
                          tinType: EIN
                          tinValue: '123456789'
                      summary:
                        minRate: 65.87
                        maxRate: 266.88
                        avgRate: 147.03
                        instances: 6
                  '1972767655':
                    - code: '99214'
                      codeType: CPT
                      negotiatedPrices:
                        - negotiatedRate: 104.46
                          expirationDate: '2024-12-31'
                          serviceCodes:
                            - '11'
                          billingClass: professional
                          negotiatedType: negotiated
                          tinType: EIN
                          tinValue: '555666777'
                        - negotiatedRate: 108.22
                          expirationDate: null
                          serviceCodes: []
                          billingClass: null
                          negotiatedType: negotiated
                          tinType: null
                          tinValue: null
                        - negotiatedRate: 112.88
                          expirationDate: '2024-12-31'
                          serviceCodes:
                            - '22'
                          billingClass: professional
                          negotiatedType: negotiated
                          tinType: EIN
                          tinValue: '555666777'
                        - negotiatedRate: 115.9
                          expirationDate: null
                          serviceCodes: []
                          billingClass: null
                          negotiatedType: negotiated
                          tinType: null
                          tinValue: null
                        - negotiatedRate: 119.33
                          expirationDate: '2024-12-31'
                          serviceCodes:
                            - '11'
                          billingClass: professional
                          negotiatedType: negotiated
                          tinType: EIN
                          tinValue: '555666777'
                        - negotiatedRate: 123.45
                          expirationDate: null
                          serviceCodes: []
                          billingClass: null
                          negotiatedType: negotiated
                          tinType: null
                          tinValue: null
                        - negotiatedRate: 135.67
                          expirationDate: '2024-12-31'
                          serviceCodes:
                            - '11'
                          billingClass: professional
                          negotiatedType: negotiated
                          tinType: EIN
                          tinValue: '555666777'
                        - negotiatedRate: 169.37
                          expirationDate: null
                          serviceCodes: []
                          billingClass: null
                          negotiatedType: negotiated
                          tinType: null
                          tinValue: null
                      summary:
                        minRate: 104.46
                        maxRate: 169.37
                        avgRate: 117.78
                        instances: 8
                meta:
                  planId: '942404110'
                  planName: UHC Choice Plus POS
                  payer: UNH
                  requestId: req_cf7f67790f92
                  timestamp: '2025-06-15T23:15:48.734729Z'
                  processingTimeMs: 912
                  inNetworkRecordsCount: 14
            noPricingData:
              summary: No pricing data found
              description: Valid plan but no pricing records for the requested NPI
              value:
                data:
                  '1750744835': []
                meta:
                  planId: '881570490'
                  planName: UHC Choice Plus POS
                  payer: UNH
                  requestId: req_6e07ffa1d88c
                  timestamp: '2025-07-10T21:49:17.246840Z'
                  processingTimeMs: 1904
                  inNetworkRecordsCount: 0
    BadRequest:
      description: Bad Request - Invalid request parameters or plan not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidNPI:
              summary: Invalid NPI format
              value:
                title: Bad Request
                status: 400
                detail: NPI '123456789' is invalid. NPIs must be exactly 10 digits.
                instance: /pricing/in-network
                requestId: req_error123
                timestamp: '2024-01-15T14:30:00Z'
            planNotFound:
              summary: Plan not found
              value:
                title: Bad Request
                status: 400
                detail: Plan ID '881570490' not found in our database.
                instance: /pricing/in-network
                requestId: req_error456
                timestamp: '2024-01-15T14:30:00Z'
    Unauthorized:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingApiKey:
              summary: Missing API key
              value:
                title: Unauthorized
                status: 401
                detail: API key is required. Include X-API-Key header in your request.
                instance: /pricing/in-network
                requestId: req_error456
                timestamp: '2024-01-15T14:30:00Z'
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            insufficientPermissions:
              summary: Insufficient permissions
              value:
                title: Forbidden
                status: 403
                detail: >-
                  Your API key does not have permission to access pricing data.
                  Upgrade your plan or contact support.
                instance: /pricing/in-network
                requestId: req_error789
                timestamp: '2024-01-15T14:30:00Z'
    PayloadTooLarge:
      description: Payload Too Large - Too many NPIs in request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            tooManyNPIs:
              summary: Too many NPIs
              value:
                title: Payload Too Large
                status: 413
                detail: >-
                  Request contains 55 NPIs. Maximum allowed is 50 NPIs per
                  request.
                instance: /pricing/in-network
                requestId: req_error101
                timestamp: '2024-01-15T14:30:00Z'
    UnprocessableEntity:
      description: Unprocessable Entity - Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
          examples:
            validationError:
              summary: Validation error
              value:
                title: Unprocessable Entity
                status: 422
                detail: One or more validation errors occurred.
                instance: /pricing/in-network
                requestId: req_error500
                timestamp: '2024-01-15T14:30:00Z'
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimitExceeded:
              summary: Rate limit exceeded
              value:
                title: Too Many Requests
                status: 429
                detail: Rate limit exceeded.
                instance: /pricing/in-network
                requestId: req_error303
                timestamp: '2024-01-15T14:30:00Z'
    InternalServerError:
      description: Internal Server Error - Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            serverError:
              summary: Internal server error
              value:
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred. Our team has been notified.
                instance: /pricing/in-network
                requestId: req_error404
                timestamp: '2024-01-15T14:30:00Z'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        Your API key for authentication. Include this header in all requests.


        **Note**: When using the API Gateway
        (care-navigation-gateway-ccg16t89.wl.gateway.dev), 

        use query parameter authentication instead: ?key=YOUR_API_KEY


        Get your API key by reaching out to support@docaroo.com.

````