InsurancePlan

Overview

The InsurancePlan resource represents health insurance products and plans offered by payer organizations. It defines coverage details, networks, and plan-specific information within provider directories.

Key Use Cases:

• Discover available insurance plans and products
• Find plans by coverage area or network
• Verify plan details and benefits
• Locate plans offered by specific payers

Relationships to Other Resources:

• Organization - Payer organizations that own or administer plans
• Location - Geographic coverage areas for plans
• OrganizationAffiliation - Network relationships for plan coverage

Resource Schema

Key fields in the InsurancePlan resource:

{
  "resourceType": "InsurancePlan",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/plan-id",
      "value": "PLAN-123"
    }
  ],
  "status": "draft|active|retired|unknown",
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-type",
          "code": "medical",
          "display": "Medical"
        }
      ]
    }
  ],
  "name": "Premium Health Plan Gold",
  "alias": ["Gold Plan", "Premium Gold"],
  "period": {
    "start": "2024-01-01",
    "end": "2024-12-31"
  },
  "ownedBy": {
    "reference": "Organization/payer-123",
    "display": "California Health Insurance"
  },
  "administeredBy": {
    "reference": "Organization/admin-456",
    "display": "Health Plan Services"
  },
  "coverageArea": [
    {
      "reference": "Location/coverage-ca",
      "display": "California"
    }
  ],
  "contact": [
    {
      "purpose": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/contactentity-type",
            "code": "ADMIN"
          }
        ]
      },
      "telecom": [
        {
          "system": "phone",
          "value": "(800) 555-PLAN",
          "use": "work"
        }
      ]
    }
  ],
  "endpoint": [
    {
      "reference": "Endpoint/plan-portal"
    }
  ],
  "network": [
    {
      "reference": "Organization/network-west"
    }
  ],
  "coverage": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-coverage-type",
            "code": "medical",
            "display": "Medical"
          }
        ]
      },
      "benefit": [
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-benefit-type",
                "code": "primary-care",
                "display": "Primary Care"
              }
            ]
          }
        }
      ]
    }
  ]
}

Key Fields:

• name - Plan name and aliases
• ownedBy - Payer organization that owns the plan
• coverageArea - Geographic areas where plan is available
• network - Provider networks included in the plan
• coverage - Types of coverage and benefits offered
• contact - Plan contact information

Operations

Read

Retrieve a specific insurance plan by ID.

Production

GET /InsurancePlan/{id}

Example Request

curl -X GET https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/InsurancePlan/plan-123 \
    -H "Accept: application/fhir+json"

Preview

GET /InsurancePlan/{id}

Example Request

curl -X GET https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/InsurancePlan/plan-123 \
    -H "Accept: application/fhir+json"

Search

Search for insurance plans using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production

GET /InsurancePlan?parameter=value

Preview

GET /InsurancePlan?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /InsurancePlan/_search

Preview

POST /InsurancePlan/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
administered-by	reference	No	Organization that administers plan	administered-by=Organization/admin-456
coverage-area	reference	No	Geographic coverage area	coverage-area=Location/coverage-ca
name	string	No	Plan name (partial match)	name=Gold
owned-by	reference	No	Payer organization that owns plan	owned-by=Organization/payer-123
plan-type	token	No	Insurance plan type	plan-type=medical
status	token	No	Plan status	status=active
type	token	No	Plan type	type=medical

Common Search Patterns

Find plans by payer:

GET /InsurancePlan?owned-by=Organization/payer-123&_count=10

Search active plans:

GET /InsurancePlan?status=active

Find plans by coverage area:

GET /InsurancePlan?coverage-area=Location/coverage-ca

Search by plan name:

GET /InsurancePlan?name=Gold&status=active

Examples

Request Examples

Production

Find plans by payer organization

curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/InsurancePlan/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "owned-by=Organization/payer-123&status=active"

Search plans by name and coverage area

curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/InsurancePlan/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Premium&coverage-area=Location/coverage-ca"

Find medical plans with payer details

curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/InsurancePlan/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "type=medical&_include=InsurancePlan:owned-by"

Preview

Find plans by payer organization

curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/InsurancePlan/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "owned-by=Organization/payer-123&status=active"

Search plans by name and coverage area

curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/InsurancePlan/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Premium&coverage-area=Location/coverage-ca"

Find medical plans with payer details

curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/InsurancePlan/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "type=medical&_include=InsurancePlan:owned-by"

Response Examples

Successful Search Response

InsurancePlan Search Bundle

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "InsurancePlan",
        "id": "plan-123",
        "status": "active",
        "type": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-type",
                "code": "medical",
                "display": "Medical"
              }
            ]
          }
        ],
        "name": "Premium Health Plan Gold",
        "alias": ["Gold Plan"],
        "ownedBy": {
          "reference": "Organization/payer-456",
          "display": "California Health Insurance"
        },
        "coverageArea": [
          {
            "reference": "Location/coverage-ca",
            "display": "California"
          }
        ],
        "contact": [
          {
            "purpose": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/contactentity-type",
                  "code": "ADMIN"
                }
              ]
            },
            "telecom": [
              {
                "system": "phone",
                "value": "(800) 555-GOLD",
                "use": "work"
              }
            ]
          }
        ],
        "coverage": [
          {
            "type": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-coverage-type",
                  "code": "medical",
                  "display": "Medical"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Integration Patterns

Common Workflows

1. Find Plans by Payer

# Step 1: Find payer organization
GET /Organization?type=pay&name=Health Insurance

# Step 2: Get all plans owned by payer
GET /InsurancePlan?owned-by=Organization/payer-123

# Step 3: Get coverage area details
GET /Location/coverage-ca

2. Plan Network Discovery

# Step 1: Find insurance plan
GET /InsurancePlan?name=Gold Plan&status=active

# Step 2: Get network organizations
GET /Organization?network=Organization/network-west

# Step 3: Find providers in network
GET /OrganizationAffiliation?primary-organization=Organization/network-west

Related Resources

• Organization - Payer organizations and networks
• Location - Coverage areas
• OrganizationAffiliation - Network relationships

Include Parameters

Use _include to fetch related resources:

# Get plans with payer organization details
GET /InsurancePlan?status=active&_include=InsurancePlan:owned-by

# Get plans with coverage area details
GET /InsurancePlan?name=Premium&_include=InsurancePlan:coverage-area

Error Handling

The InsurancePlan resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.

InsurancePlan-Specific Error Scenarios

• 404 Not Found: InsurancePlan ID doesn't exist or plan is inactive
• 400 Bad Request: Invalid plan type codes or malformed organization references
• Empty Results: No insurance plans match the search criteria

Troubleshooting Tips

• No Payer Results: Verify payer organization references are valid
• Coverage Area Issues: Ensure coverage area locations exist
• Status Filtering: Use status=active to find current plans only

Supported Profiles

• HL7 FHIR R4 InsurancePlan
• DaVinci PDex Plan-Net InsurancePlan