Platform Docs / 03-API-REFERENCE/ENDPOINTS-PAYER-PLANS.md

Endpoints — Payer Plans

← Back to Platform Architecture

Endpoints — Payer Plans

Payer plan management endpoints for accessing, searching, and managing insurance plan coverage policies.

GET /api/payer-plans

Search payer plans with filtering. Authentication: Required (X-User-Id header) Authorization: Any authenticated user Credit Cost: None (read-only)

Query Parameters

Response (200 OK)

{
  "plans": [
    {
      "id": "plan-uuid",
      "payer_name": "Cigna",
      "plan_name": "Cigna Open Access 2000",
      "plan_year": 2024,
      "state": "WA",
      "plan_type": "PPO",
      "coverage_data": {
        "behavioral_health": {
          "iop": {
            "frequency_limit": "60 days per benefit year",
            "requires_prior_auth": true,
            "copay": "$30",
            "deductible": "$1000",
            "out_of_pocket_max": "$5000"
          },
          "php": {
            "frequency_limit": "45 days per benefit year",
            "requires_prior_auth": true
          }
        },
        "medical_necessity_criteria": {
          "description": "Review based on functional status, not service duration",
          "gaf_threshold": 35,
          "requires_clinical_documentation": true
        },
        "appeal_process": {
          "initial_appeal_days": 30,
          "expedited_days": 72,
          "address": "Cigna Appeals, 900 Cottage Grove Rd, Hartford, CT 06152",
          "phone": "1-800-CIGNA-CC",
          "fax": "860-226-2847"
        }
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-04-14T10:30:00Z"
    }
  ],
  "total": 487,
  "limit": 25,
  "offset": 0
}

GET /api/payer-plans/:id

Retrieve a specific payer plan. Authentication: Required Authorization: Any authenticated user Credit Cost: None

Response (200 OK)

Full plan object with complete coverage_data JSONB structure.

Errors

404 Not Found — Plan doesn't exist 
{ "error": "Plan not found" }

POST /api/payer-plans

Create or update a payer plan (admin only). Authentication: Required Authorization: admin role only PHI Validation: Request scanned for PHI

Request Body

{
  "payer_name": "Cigna",
  "plan_name": "Cigna Open Access 2000",
  "plan_year": 2024,
  "state": "WA",
  "plan_type": "PPO",
  "coverage_data": {
    "behavioral_health": {
      "iop": {
        "frequency_limit": "60 days per benefit year",
        "requires_prior_auth": true,
        "copay": "$30",
        "deductible": "$1000"
      }
    },
    "medical_necessity_criteria": {
      "description": "Review based on functional status",
      "gaf_threshold": 35
    },
    "appeal_process": {
      "initial_appeal_days": 30,
      "expedited_days": 72,
      "address": "...",
      "phone": "...",
      "fax": "..."
    }
  }
}

Response (201 Created or 200 OK)

Returns created/updated plan.

Errors

403 Forbidden — User not admin 
{ "error": "Unauthorized: admin role required" }

GET /api/payer-plans/search

Advanced plan search with JSONB filtering. Authentication: Required Authorization: Any authenticated user Credit Cost: None

Query Parameters

ParameterTypeDefaultExample
limitinteger2550
offsetinteger0100
payer_namestring(none)Cigna
plan_yearinteger(none)2024
statestring(none)CA, WA
servicestring(none)IOP, PHP
ParameterTypeExample
payerstringCigna
statestringWA, CA
gaf_thresholdinteger35
requires_prior_authbooleantrue
servicestringIOP

Response (200 OK)

Array of plans matching criteria.

Coverage Data Structure

The coverage_data JSONB field contains: 
{
  "behavioral_health": {
    "iop": {
      "frequency_limit": "60 days per benefit year",
      "requires_prior_auth": boolean,
      "copay": "$30",
      "deductible": "$1000",
      "out_of_pocket_max": "$5000"
    },
    "php": { ... },
    "residential": { ... },
    "inpatient": { ... }
  },
  "medical_necessity_criteria": {
    "description": "How payer evaluates medical necessity",
    "gaf_threshold": 35,
    "requires_clinical_documentation": true
  },
  "appeal_process": {
    "initial_appeal_days": 30,
    "expedited_days": 72,
    "standard_appeal_days": 30,
    "address": "...",
    "phone": "...",
    "fax": "...",
    "email": "..."
  },
  "denial_triggers": [
    "Frequency limit exceeded",
    "Service not covered",
    "Prior authorization not obtained"
  ]
}

Plan Drift Detection

The system monitors payer plans for policy changes: