openapi: 3.0.1
info:
  title: Nirvana Coverage Cost Estimation Coverage Scan API
  description: Nirvana's Coverage API verifies a patient's insurance eligibility, estimates their financial responsibility for an appointment, identifies plan-level details that could lead to a denial, and recovers active insurance using only basic demographic information. Responses normalize complex payer data into structured, consistent JSON for behavioral and mental health workflows.
  termsOfService: https://www.meetnirvana.com
  contact:
    name: Nirvana Support
    url: https://www.meetnirvana.com
  version: v1
servers:
- url: https://coverage-api.meetnirvana.com
  description: Nirvana Coverage API production server
security:
- apiKeyHeader: []
tags:
- name: Coverage Scan
  description: Multi-payer coverage discovery.
paths:
  /v1/scan:
    post:
      operationId: scan_v1_scan_post
      tags:
      - Coverage Scan
      summary: Scan payers for active coverage
      description: Scan multiple payers to find any active coverage a patient may have when the payer is unknown.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CoverageRequest'
      responses:
        '200':
          description: Matched coverage results across scanned payers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Request could not be processed (validation error).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error code for error-handling logic.
        message:
          type: string
          description: Human-readable message for troubleshooting and debugging.
        errors:
          type: array
          description: Field-level validation errors, when present.
          items:
            type: string
    Benefits:
      type: object
      description: Payer-normalized, specialty-specific benefit details.
      properties:
        copay:
          type: number
          format: float
          description: Patient copay for the service.
        coinsurance:
          type: number
          format: float
          description: Patient coinsurance percentage.
        deductible:
          type: number
          format: float
          description: Plan deductible amount.
        remaining_deductible:
          type: number
          format: float
          description: Deductible remaining to be met.
        out_of_pocket_max:
          type: number
          format: float
          description: Plan out-of-pocket maximum.
        remaining_out_of_pocket:
          type: number
          format: float
          description: Out-of-pocket maximum remaining.
        session_limit:
          type: integer
          description: Number of covered sessions per benefit period, when applicable.
        prior_authorization_required:
          type: boolean
          description: Whether prior authorization is required for the service.
        telehealth_covered:
          type: boolean
          description: Whether telehealth is covered under the plan.
    CoverageRequest:
      type: object
      required:
      - member_first_name
      - member_last_name
      - member_dob
      - provider_npi
      properties:
        member_first_name:
          type: string
          description: Patient's first name.
        member_last_name:
          type: string
          description: Patient's last name.
        member_dob:
          type: string
          format: date
          description: Patient's date of birth (YYYY-MM-DD).
        member_id:
          type: string
          description: Member ID, when available.
        member_gender:
          type: string
          enum:
          - M
          - F
          description: Patient gender.
        provider_npi:
          type: string
          minLength: 10
          maxLength: 10
          description: 10-digit provider National Provider Identifier.
        payer_id:
          type: string
          description: Payer identifier, when known.
        office_id:
          type: string
          description: Your office identifier.
        patient_id:
          type: string
          description: Your internal patient identifier.
        patient_state:
          type: string
          description: Patient's state of residence.
        next_appointment:
          type: string
          format: date
          description: Date of the patient's next appointment (YYYY-MM-DD).
        patient_type:
          type: string
          enum:
          - PROSPECT
          - NEW_PATIENT
          - EXISTING_PATIENT
          description: Patient relationship type.
        cpt_code:
          type: string
          description: CPT procedure code for the planned service.
        modality_code:
          type: string
          default: PSY
          description: Specialty modality code (defaults to PSY for behavioral health).
        with_alerts:
          type: boolean
          default: false
          description: Include plan-level denial-risk alerts in the response.
    CoverageResult:
      type: object
      properties:
        coverage_status:
          type: string
          description: Active or inactive coverage status for the patient.
        payer_name:
          type: string
          description: Normalized payer name.
        plan_name:
          type: string
          description: Normalized plan name.
        benefits:
          $ref: '#/components/schemas/Benefits'
        alerts:
          type: array
          description: Plan-level alerts that could lead to a denial.
          items:
            type: string
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: Nirvana issues an API key on request. Pass it in the `apikey` request header on every call. Contact Nirvana to provision a key.