Claims

Manages the full lifecycle of medical claims — from submission through adjudication, prior authorization, and payment.

Overview

The Claims service is the financial adjudication core of Olly. It receives claims submitted by members or providers, validates them against eligibility and plan benefits, and drives them through a state machine from SUBMITTED through APPROVED/REJECTED to PAID.

Each claim may have multiple ClaimLine items (individual service line entries), attached supporting documents, and an optional prior authorization link. The service coordinates with Eligibility to verify coverage at time of service, with Policy Admin to apply benefit rules (deductibles, copays, coinsurance), and with Billing to trigger provider payment once a claim is approved.

Prior authorization is managed within the same service. A PriorAuth record must exist and be in APPROVED status for procedures that require pre-authorization before a claim can advance past review.

Responsibilities

• Accept claim submissions from members, providers, and internal systems
• Validate member eligibility and coverage at the date of service via the Eligibility service
• Enforce prior authorization requirements using the PriorAuth sub-domain
• Drive claim state transitions: SUBMITTED → IN_REVIEW → APPROVED/REJECTED → PAID/CLOSED
• Manage ClaimLine items for individual service line adjudication
• Accept and store supporting claim documents
• Publish adjudication events for downstream Billing and Notifications consumption
• Expose internal endpoints for Billing to retrieve claim details and trigger payment

Database

Schema: claims

Table	Purpose
claims	Root claim aggregate with status, member, policy, and financial fields
claim_lines	Individual service line items (procedure codes, billed amounts, allowed amounts)
claim_documents	Supporting documents attached to a claim
prior_auths	Prior authorization requests and approvals
outbox	Transactional outbox for reliable Kafka event publishing

API Routes

Method	Path	Auth	Description
POST	/claims	JWT	Submit a new claim
GET	/claims	JWT	List claims (filterable)
GET	/claims/{locator}	JWT	Get claim by locator
PATCH	/claims/{locator}/review	JWT	Move claim to IN_REVIEW
PATCH	/claims/{locator}/approve	JWT	Approve a claim
PATCH	/claims/{locator}/reject	JWT	Reject a claim with reason code
PATCH	/claims/{locator}/requestInfo	JWT	Request additional information
PATCH	/claims/{locator}/close	JWT	Close a claim
POST	/claims/{locator}/number/generate	JWT	Generate a display claim number
POST	/claims/{locator}/lines	JWT	Add a ClaimLine to a claim
GET	/claims/{locator}/lines/list	JWT	List all ClaimLines for a claim
POST	/claims/{locator}/documents	JWT	Attach a document to a claim
GET	/claims/{locator}/documents/list	JWT	List documents attached to a claim
POST	/prior-auth	JWT	Submit a prior authorization request
GET	/prior-auth	JWT	List prior authorizations
GET	/prior-auth/{locator}	JWT	Get prior auth by locator
PATCH	/prior-auth/{locator}/review	JWT	Move prior auth to review
PATCH	/prior-auth/{locator}/approve	JWT	Approve a prior authorization
PATCH	/prior-auth/{locator}/deny	JWT	Deny a prior authorization
GET	/internal/claims/{locator}	Internal	Retrieve claim for Billing service
PATCH	/internal/claims/{locator}/pay	Internal	Mark claim as paid (called by Billing)

Events

Publishes

Topic	When
claims.submitted	A new claim is successfully submitted
claims.approved	A claim transitions to APPROVED
claims.rejected	A claim is rejected with a reason code
claims.adjudicated	Adjudication is complete (approved or rejected)
claims.paid	Payment is confirmed by Billing via the internal pay endpoint

Consumes

The Claims service does not consume Kafka events directly. It is a consumer target for other services (Billing calls its internal endpoints; Notifications subscribes to its events).

Dependencies

Service	How used
Eligibility	Validates member coverage at date of service via HTTP before approving a claim
Enrollment	Fetches policy details to confirm plan membership
Policy Admin	Retrieves benefit rules and plan configuration for adjudication

Key Design Decisions

Outbox pattern for event publishing: All Kafka events are written to the outbox table within the same database transaction as the claim state change. A background worker polls and publishes to Kafka, ensuring no events are lost even if the broker is temporarily unavailable.

Internal pay endpoint: Billing drives the payment confirmation by calling PATCH /internal/claims/{locator}/pay. This keeps payment orchestration in Billing while Claims owns the state machine. The internal route is protected at the gateway level rather than requiring a JWT.