Benefits Chat

RAG-powered chatbot for querying payer benefit information using natural language. Provides answers grounded in actual payer policy documents with source citations.

How It Works

The Benefits Chat uses Retrieval-Augmented Generation (RAG) to search indexed payer documents, retrieve relevant context, and generate accurate responses with citations to source documents.

Query benefits

Ask a natural language question about payer benefits. Optionally filter to a specific payer for targeted results.

POST/chat/query

Body Parameters

questionstringrequired

Natural language question about benefits.

payer_slugstringoptional

Filter to specific payer (e.g., aetna, cigna, uhc).

conversation_historyarrayoptional

Previous messages for context.

Request

curl https://api.isomera.ai/v1/chat/query \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the PA requirements for biologics?",
    "payer_slug": "aetna"
  }'

Response

{
  "answer": "Prior authorization for biologics under Aetna requires documentation of diagnosis, previous treatments tried, and clinical justification. The provider must submit the request via the Aetna provider portal or fax. Typical turnaround time is 2-5 business days.",
  "sources": [
    {
      "document_title": "Aetna Prior Authorization Guidelines 2024",
      "document_url": "https://...",
      "chunk_text": "Biologics require prior authorization...",
      "relevance_score": 0.92
    },
    {
      "document_title": "Aetna Specialty Drug Policy",
      "document_url": "https://...",
      "chunk_text": "Step therapy requirements...",
      "relevance_score": 0.87
    }
  ],
  "payer_slug": "aetna",
  "timestamp": "2024-12-18T10:30:00Z"
}

Multi-payer query

Compare benefits across multiple payers with a single query. Useful for helping patients understand coverage differences.

POST/chat/query/multi-payer

Body Parameters

questionstringrequired

Natural language question about benefits.

payer_slugsarrayrequired

List of payer slugs to compare.

Request

curl https://api.isomera.ai/v1/chat/query/multi-payer \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the copay for specialist visits?",
    "payer_slugs": ["aetna", "cigna", "uhc"]
  }'

Response

{
  "question": "What is the copay for specialist visits?",
  "payers": {
    "aetna": {
      "answer": "Specialist copays range from $40-$60 depending on plan tier...",
      "sources": [...]
    },
    "cigna": {
      "answer": "Cigna specialist visits typically have a $50 copay...",
      "sources": [...]
    },
    "uhc": {
      "answer": "UnitedHealthcare specialist copays vary by network...",
      "sources": [...]
    }
  },
  "timestamp": "2024-12-18T10:30:00Z"
}

Chat sessions

Manage persistent chat sessions with conversation history. Sessions are user-scoped and require authentication.

List sessions

GET/chat/sessions

Query Parameters

limitintegeroptional

Maximum sessions to return.

Default: 20

Create session

POST/chat/sessions

Body Parameters

titlestringoptional

Session title for identification.

payer_filterstringoptional

Default payer filter for this session.

Get session

GET/chat/sessions/{session_id}

Delete session

DELETE/chat/sessions/{session_id}

List sessions response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Keytruda coverage question",
    "payer_filter": "aetna",
    "message_count": 5,
    "created_at": "2024-12-18T10:00:00Z",
    "updated_at": "2024-12-18T10:30:00Z"
  }
]

Create session request

{
  "title": "Benefits inquiry",
  "payer_filter": "cigna"
}

Send message in session

Send a message within an existing session. The conversation history is automatically included for context.

POST/chat/sessions/{session_id}/messages

Path Parameters

session_idstringrequired

The session UUID.

Body Parameters

questionstringrequired

The question to ask.

Request

curl https://api.isomera.ai/v1/chat/sessions/550e8400.../messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What about step therapy requirements?"
  }'

Response

{
  "answer": "Building on our previous discussion about Keytruda, step therapy is typically required before approval...",
  "sources": [...],
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_title": "Keytruda coverage question"
}

Supported payers

The system has indexed policy documents from major commercial payers and state Medicaid programs.

Payer Slug	Name	Documents
`aetna`	Aetna	PA policies, formulary, coverage
`cigna`	Cigna	PA policies, formulary, coverage
`uhc`	UnitedHealthcare	PA policies, formulary, coverage
`anthem`	Anthem BCBS	PA policies, formulary
`humana`	Humana	PA policies, formulary
`bcbs_tx`	BCBS Texas	PA policies, formulary
`texas_medicaid`	Texas Medicaid	PA policies, PDL
`florida_medicaid`	Florida Medicaid	PA policies, PDL

Example questions

• "What are the PA requirements for Keytruda with Aetna?"
• "Does Cigna require step therapy for biologics?"
• "What documentation is needed for specialty drug PA?"
• "How long does PA approval typically take for UHC?"
• "What is the appeals process if PA is denied?"
• "Are there quantity limits on specialty medications?"

Health check

Check if the Benefits Chat service is operational.

GET/chat/health

Request

curl https://api.isomera.ai/v1/chat/health

Response

{
  "status": "ok",
  "service": "benefits_chat"
}