InsurancePlan | MedicaSoft Technical Documentation

The InsurancePlan resource implements the FHIR R4 InsurancePlan specification

Fields

Name	Type	Cardinality	Required	Description
identifier	Identifier	0..*		Business Identifier for Product
status	code	0..1		draft \| active \| retired \| unknown PublicationStatus (Required)
type	CodeableConcept	0..*		Kind of productInsurance plan type (Example)
name	string	0..1		Official name
alias	string	0..*		Alternate names
period	Period	0..1		When the product is available
ownedBy	Reference(Organization)	0..1		Plan issuer
administeredBy	Reference(Organization)	0..1		Product administrator
coverageArea	Reference(Location)	0..*		Where product applies
contact	BackboneElement	0..*		Contact for the product
purpose	CodeableConcept	0..1		The type of contactContact entity type (Extensible)
name	HumanName	0..1		A name associated with the contact
telecom	ContactPoint	0..*		Contact details (telephone, email, etc.) for a contact
address	Address	0..1		Visiting or postal addresses for the contact
endpoint	Reference(Endpoint)	0..*		Technical endpoint
network	Reference(Organization)	0..*		What networks are Included
coverage	BackboneElement	0..*		Coverage details
type	CodeableConcept	1..1	*	Type of coverage
network	Reference(Organization)	0..*		What networks provide coverage
benefit	BackboneElement	1..*	*	List of benefits
type	CodeableConcept	1..1	*	Type of benefit
requirement	string	0..1		Referral requirements
limit	BackboneElement	0..*		Benefit limits
value	Quantity	0..1		Maximum value allowed
code	CodeableConcept	0..1		Benefit limit details
plan	BackboneElement	0..*		Plan details
identifier	Identifier	0..*		Business Identifier for Product
type	CodeableConcept	0..1		Type of plan
coverageArea	Reference(Location)	0..*		Where product applies
network	Reference(Organization)	0..*		What networks provide coverage
generalCost	BackboneElement	0..*		Overall costs
type	CodeableConcept	0..1		Type of cost
groupSize	positiveInt	0..1		Number of enrollees
cost	Money	0..1		Cost value
comment	string	0..1		Additional cost information
specificCost	BackboneElement	0..*		Specific costs
category	CodeableConcept	1..1	*	General category of benefit
benefit	BackboneElement	0..*		Benefits list
type	CodeableConcept	1..1	*	Type of specific benefit
cost	BackboneElement	0..*		List of the costs
type	CodeableConcept	1..1	*	Type of cost
applicability	CodeableConcept	0..1		in-network \| out-of-network \| otherBenefit cost applicability (Required)
qualifiers	CodeableConcept	0..*		Additional information about the cost
value	Quantity	0..1		The actual cost value
InsurancePlan	DomainResource			Details of a Health Insurance product/plan provided by an organization+ Rule: The organization SHALL at least have a name or an idendtifier, and possibly more than oneElements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
identifier	Identifier	0..*		Business Identifier for Product
status	code	0..1		draft \| active \| retired \| unknownPublicationStatus (Required)
type	CodeableConcept	0..*		Kind of productInsurance plan type (Example)
name	string	0..1		Official name
alias	string	0..*		Alternate names
period	Period	0..1		When the product is available
ownedBy	Reference(Organization)	0..1		Plan issuer
administeredBy	Reference(Organization)	0..1		Product administrator
coverageArea	Reference(Location)	0..*		Where product applies
contact	BackboneElement	0..*		Contact for the product
purpose	CodeableConcept	0..1		The type of contactContact entity type (Extensible)
name	HumanName	0..1		A name associated with the contact
telecom	ContactPoint	0..*		Contact details (telephone, email, etc.) for a contact
address	Address	0..1		Visiting or postal addresses for the contact
endpoint	Reference(Endpoint)	0..*		Technical endpoint
network	Reference(Organization)	0..*		What networks are Included
coverage	BackboneElement	0..*		Coverage details
type	CodeableConcept	1..1	*	Type of coverage
network	Reference(Organization)	0..*		What networks provide coverage
benefit	BackboneElement	1..*	*	List of benefits
type	CodeableConcept	1..1	*	Type of benefit
requirement	string	0..1		Referral requirements
limit	BackboneElement	0..*		Benefit limits
value	Quantity	0..1		Maximum value allowed
code	CodeableConcept	0..1		Benefit limit details
plan	BackboneElement	0..*		Plan details
identifier	Identifier	0..*		Business Identifier for Product
type	CodeableConcept	0..1		Type of plan
coverageArea	Reference(Location)	0..*		Where product applies
network	Reference(Organization)	0..*		What networks provide coverage
generalCost	BackboneElement	0..*		Overall costs
type	CodeableConcept	0..1		Type of cost
groupSize	positiveInt	0..1		Number of enrollees
cost	Money	0..1		Cost value
comment	string	0..1		Additional cost information
specificCost	BackboneElement	0..*		Specific costs
category	CodeableConcept	1..1	*	General category of benefit
benefit	BackboneElement	0..*		Benefits list
type	CodeableConcept	1..1	*	Type of specific benefit
cost	BackboneElement	0..*		List of the costs
type	CodeableConcept	1..1	*	Type of cost
applicability	CodeableConcept	0..1		in-network \| out-of-network \| otherBenefit cost applicability (Required)
qualifiers	CodeableConcept	0..*		Additional information about the cost
value	Quantity	0..1		The actual cost value

Interactions

Read

Get a InsurancePlan entry by id

GET /InsurancePlan/:id

Example

Request

https://r4cert.medicasoft.us/api/fhir/InsurancePlan/f08634ac-e63d-4230-aaa1-55ce0262fe36

Response

{
  "resourceType": "InsurancePlan",
  "id": "f08634ac-e63d-4230-aaa1-55ce0262fe36",
  "identifier": [
    {
      "system": "http://example.org/insuranceplans",
      "value": "IP-2023-001"
    },
    {
      "system": "http://example.org/legacy-ids",
      "value": "HMO-SILVER-2023"
    }
  ],
  "status": "active",
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-type",
          "code": "medical",
          "display": "Medical"
        }
      ]
    }
  ],
  "name": "Premium Health Insurance Silver Plan",
  "alias": [
    "Silver Health Coverage",
    "PremiumSilver"
  ],
  "period": {
    "start": "2025-01-01",
    "end": "2025-12-31"
  },
  "ownedBy": {
    "reference": "Organization/000003e8-45f0-21f0-b800-325096b39f47",
    "display": "Premium Health Insurance Group"
  },
  "administeredBy": {
    "reference": "Organization/000003e8-45f8-21f0-a000-325096b39f47",
    "display": "HealthAdmin Services"
  },
  "coverageArea": [
    {
      "reference": "Location/000003e8-45f8-21f0-bf00-325096b39f47",
      "display": "Northeast Region"
    }
  ],
  "contact": [
    {
      "purpose": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/contactentity-type",
            "code": "GENERAL",
            "display": "General Inquiries"
          }
        ]
      },
      "telecom": [
        {
          "system": "phone",
          "value": "1-800-555-1234",
          "use": "work"
        },
        {
          "system": "email",
          "value": "support@premiumhealth.example.org",
          "use": "work"
        }
      ],
      "address": {
        "line": ["123 Insurance Way", "Suite 400"],
        "city": "Boston",
        "state": "MA",
        "postalCode": "02115",
        "country": "USA"
      }
    }
  ],
  "endpoint": [
    {
      "reference": "Endpoint/example-endpoint",
      "display": "Premium Health Insurance Claims Portal"
    }
  ],
  "network": [
    {
      "reference": "Organization/network-1",
      "display": "Premium Silver Provider Network"
    }
  ],
  "coverage": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-type",
            "code": "medical",
            "display": "Medical"
          }
        ]
      },
      "benefit": [
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-type",
                "code": "medical",
                "display": "Medical"
              }
            ]
          },
          "limit": [
            {
              "value": {
                "value": 1000000,
                "unit": "USD",
                "system": "urn:iso:std:iso:4217",
                "code": "USD"
              },
              "code": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/benefit-limit",
                    "code": "lifetime",
                    "display": "Lifetime"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "plan": [
    {
      "identifier": [
        {
          "system": "http://example.org/planidentifiers",
          "value": "SILVER-2023"
        }
      ],
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/insurance-plan-type",
            "code": "medical",
            "display": "Medical"
          }
        ]
      },
      "specificCost": [
        {
          "category": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/coverage-copay-type",
                "code": "copay",
                "display": "Copay"
              }
            ]
          },
          "benefit": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/benefit-type",
                    "code": "primarycare",
                    "display": "Primary Care"
                  }
                ]
              },
              "cost": [
                {
                  "type": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/benefit-cost-type",
                        "code": "copay",
                        "display": "Copay"
                      }
                    ]
                  },
                  "value": {
                    "value": 25,
                    "unit": "USD",
                    "system": "urn:iso:std:iso:4217",
                    "code": "USD"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Search

Query InsurancePlan resources

GET /InsurancePlan?:query_parameters

Parameters

Name	Type	Description
address	string	A server defined search that may match any of the string fields in the Address, including line, city, district, state, country, postalCode, and/or text
identifier	token	Any identifier for the organization (not the accreditation issuer’s identifier)
administered-by	reference	Product administrator
name	string	A portion of the organization’s name or alias
owned-by	reference	An organization of which this organization forms a part
status	token	Is the Organization record active
type	token	A code for the type of organization

Errors

Code	Description
400	Invalid parameters
404	Resource not found