Coverage

Overview

The Coverage resource represents financial instruments used to reimburse or pay for health care products and services, including both insurance and self-payment arrangements.

Use Cases:

Retrieve patient insurance coverage information
Verify coverage eligibility and benefits
Support claims processing and billing workflows
Track insurance payor relationships

Relationships:

Patient: References the individual covered by the insurance
Organization: May reference the insurance company or payor organization
Provenance: Tracks the source and history of coverage information

Resource Schema

Key Fields:

Field	Type	Description	Required
id	string	Unique identifier for the resource	Yes
status	code	Coverage status (active, cancelled, draft, entered-in-error)	Yes
type	CodeableConcept	Coverage category (medical, dental, mental health, etc.)	No
policyHolder	Reference(Patient/RelatedPerson/Organization)	Owner of the policy	No
subscriber	Reference(Patient/RelatedPerson)	Subscriber to the policy	No
beneficiary	Reference(Patient)	Plan beneficiary	Yes
dependent	string	Dependent number	No
relationship	CodeableConcept	Beneficiary relationship to subscriber	No
period	Period	Coverage start and end dates	No
payor	Reference(Organization/Patient/RelatedPerson)[]	Issuer of the policy	Yes
class	BackboneElement[]	Additional coverage classifications	No

JSON Example:

{
  "resourceType": "Coverage",
  "id": "example-coverage-id",
  "meta": {
    "lastUpdated": "2023-09-23T21:34:00.000+00:00"
  },
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "PI"
          }
        ],
        "text": "ClientID"
      },
      "system": "urn:oid:2.16.840.1.113883.3.3569.5050.1767"
    }
  ],
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/ValueSet/coverage-type",
        "code": "pay"
      }
    ]
  },
  "beneficiary": {
    "reference": "Patient/example-patient-id",
    "type": "Patient"
  },
  "relationship": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/ValueSet/subscriber-relationship",
        "code": "self",
        "display": "Self"
      }
    ],
    "text": "Self"
  },
  "period": {
    "start": "2023-01-01T12:00:00+00:00"
  }
}

Operations

The Payer API Coverage resource supports the following operations.

CareRecord / Solution	Create	Read	Update	Delete	Search
myAvatar	-	Yes	-	-	Yes

Read

Retrieve a specific Coverage resource by its unique identifier.

GET /Coverage/{id}

Search

Search for coverage using various criteria.

POST Method

Use POST for searches with form-encoded parameters. POST is recommended as it keeps PHI out of URLs and server logs.

POST /Coverage/_search

GET Method

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

GET /Coverage?parameter=value

info

Not all Netsmart solutions support Coverage search. See supported operations table above and consult your target solution's documentation for more information.

Search Parameters

Patient-based Search:

Parameter	Type	Required	Description	Example
`patient`	reference	Yes	Retrieve coverages for a patient	`patient=value`
`payor`	reference	No	The identity of the insurer or party paying for services	`payor=value`
`_lastUpdated`	date	No	Only return resources which were last updated as specified by the given range	`_lastUpdated=value`
`_revinclude`	special	No	Include Provenance resource(s) that reference the matched search results. Allowed: "Provenance:target"	`_revinclude=value`

ID-based Search:

Parameter	Type	Required	Description	Example
`_id`	string	Yes	The ID of the resource	`_id=value`
`_lastUpdated`	date	No	Only return resources which were last updated as specified by the given range	`_lastUpdated=value`
`_revinclude`	special	No	Include Provenance resource(s) that reference the matched search results. Allowed: "Provenance:target"	`_revinclude=value`

Examples

Read Coverage by ID

Production
Preview

Read Coverage by ID
curl -X GET https://fhir.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Coverage/{id} \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Read Coverage by ID
curl -X GET https://fhirtest.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Coverage/{id} \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Search by Patient

Production
Preview

Search by Patient
curl -X POST https://fhir.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Coverage/_search \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/123"

Search by Patient
curl -X POST https://fhirtest.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Coverage/_search \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/123"

Search by Patient and Payor

Production
Preview

Search by Patient and Payor
curl -X POST https://fhir.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Coverage/_search \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/123" \
    -d "payor=Organization/insurance-456"

Search by Patient and Payor
curl -X POST https://fhirtest.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Coverage/_search \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/123" \
    -d "payor=Organization/insurance-456"

Integration Patterns

Common Workflows:

Retrieve all coverage records for a patient during eligibility verification
Filter coverage by payor to identify specific insurance relationships
Include provenance data to track coverage information sources
Cross-reference with patient demographics for comprehensive coverage view

Related Resources:

Patient - Individual covered by the insurance
Organization - Insurance company or payor organization
Provenance - Source and history tracking

Error Handling

For detailed error codes and handling procedures, see the Error Handling Guide.

Supported Profiles

This resource supports the following FHIR profiles as defined in the CapabilityStatement:

Overview​

Resource Schema​

Operations​

Read​

Search​

POST Method​

GET Method​

Search Parameters​

Examples​

Read Coverage by ID​

Search by Patient​

Search by Patient and Payor​

Integration Patterns​

Error Handling​

Supported Profiles​