Providers

The provider service manages healthcare providers — GPs, hospitals, specialists, pharmacies — including their credentialing status, network participation, and directory listing.

---

Provider Entity

A Provider record represents a credentialed healthcare organisation or individual practitioner.

type Provider struct {
    ID            uuid.UUID
    Locator       string        // e.g. "PRV-2026-000042"
    NPI           string        // National Provider Identifier (unique)
    PartyID       uuid.UUID     // links to the Party record (PROVIDER type)
    Name          string
    Specialty     string        // e.g. "CARDIOLOGY", "GENERAL_PRACTICE"
    NetworkStatus NetworkStatus // PENDING | ACTIVE | INACTIVE
    Address       []byte        // jsonb
    Phone         string
    Email         string
    ActivatedAt   *time.Time    // set when NetworkStatus → ACTIVE
}

The NPI (National Provider Identifier) is the primary business key for cross-system identification. It is unique across the platform and used in EDI 837 transactions, FHIR resources, and prior auth requests.

---

Credentialing Lifecycle

Before a provider can be added to the network (NetworkStatus = ACTIVE), they must complete a credentialing review. The credentialing workflow is implemented as a Temporal workflow to handle the multi-week human review process with reliable state persistence.

CredentialingRequest Fields

Field	Notes
ProviderID	The provider being credentialed
Status	SUBMITTED, APPROVED, or REJECTED
SubmittedAt	Timestamp of application submission
ReviewedAt	Timestamp of final reviewer decision
ReviewerNotes	Free-text notes from the credentialing reviewer

When a CredentialingRequest moves to APPROVED, the Temporal workflow updates Provider.NetworkStatus = ACTIVE and sets Provider.ActivatedAt. The provider directory in OpenSearch is re-indexed automatically.

---

In-Network vs. Out-of-Network Impact on Claims

Network status is checked synchronously (gRPC) by the Claims service during adjudication. The result directly affects how much the plan pays:

Scenario	Allowed Amount	Member Cost-Sharing
In-network (ACTIVE)	Contracted rate (negotiated discount from billed amount)	Deductible + coinsurance at the in-network rate (lower)
Out-of-network (INACTIVE / PENDING)	Usual, customary, and reasonable (UCR) rate	Deductible + coinsurance at the out-of-network rate (higher), or claim denied if plan has strict network requirements

If a provider's NetworkStatus is PENDING (credentialing in progress), their claims may be held in PENDING_INFO until credentialing resolves, depending on plan configuration.

---

Provider Directory (OpenSearch-Indexed)

The provider directory is a full-text and geo-filtered search index powered by Amazon OpenSearch. Each time a Provider record changes (new credentialing approval, specialty update, address change), the provider service publishes a provider.updated Kafka event. A consumer re-indexes the document in OpenSearch.

Searchable fields:

• Provider name and NPI
• Specialty (controlled vocabulary)
• Address (geo-point for proximity search)
• Network status
• Languages spoken (stored in the Address JSONB extension)

Members and employers query the directory via the APISIX-proxied /providers/search endpoint, which delegates to the OpenSearch provider.providers index. The AI platform also uses this index for augmented provider extraction from unstructured text (NPPES/CAQH documents).

---

Key Go Struct Fields at a Glance

type Provider struct {
    NPI           string        // primary business key
    Specialty     string
    NetworkStatus NetworkStatus // PENDING | ACTIVE | INACTIVE
    ActivatedAt   *time.Time    // nil until first ACTIVE
}

type CredentialingRequest struct {
    ProviderID    uuid.UUID
    Status        CredentialingStatus // SUBMITTED | APPROVED | REJECTED
    SubmittedAt   time.Time
    ReviewedAt    *time.Time
    ReviewerNotes string
}