Insurance and Benefits Eligibility Checks | Medplum

Overview

The Stedi integration allows you to perform insurance eligibility checks by sending a a CoverageEligibilityRequest resource and receiving a CoverageEligibilityResponse resource with the benefits information. This workflow is handled by our Insurance Eligibility Bot. Please contact the Medplum team to get access to this bot.

For more general information about eligibility checks, please see our Insurance Eligibility Checks guide.

Creating the Eligibility Check

The following diagram shows the resources that are involved to make an insurance eligibility check with our Stedi integration.

CoverageEligibilityRequest

Field Description Required
insurer Reference to the payer Organization Yes
provider Reference to the provider Organization Yes
subscriber Reference to the subscriber Patient Yes
insurance Array of Coverages. If there are more than one, the array item labeled as the focal will be used for the eligibility check Yes
servicedPeriod.start Service period start date No
item Array of details about the eligibility being checked. Including procedure, product, or service being provided No

Service type codes

Codes

Code Display
30 Health Benefit Plan Coverage
12 Durable Medical Equipment Purchase
35 Dental Care
47 Hospital
48 Hospital - Inpatient
50 Hospital - Outpatient
88 Pharmacy
98 Professional (Physician) Visit - Office
AL Vision (Optometry)
MH Mental Health
UC Urgent Care

Organization (Payer)

Field Description Required
identifier System must be https://www.stedi.com/healthcare/network Yes
name Organization name Yes

Organization (Provider)

Field Description Required
identifier System must be http://hl7.org/fhir/sid/us-npi Yes
name Organization name Yes

Patient (Subscriber)

Field Description Required
name.family Last name Yes
name.given First name Yes
birthDate Date of birth Yes
identifier System http://hl7.org/fhir/sid/us-ssn No

Coverage

Field Description Required
subscriberId Insurance subscriber ID Yes
status Should be "active" Yes
subscriber Reference to a Patient or RelatedPerson Yes
beneficiary Reference to a Patient or RelatedPerson Yes
payor Reference to the payer Organization Yes

Executing the Eligibility Check

The Insurance Eligibility Bot runs the Stedi (X12 270/271) eligibility check and returns a CoverageEligibilityResponse. Invoke the $stedi-check-eligibility custom operation on CoverageEligibilityRequest.

Sample FHIR API call

POST {base}/fhir/R4/CoverageEligibilityRequest/{id}/$stedi-check-eligibility

Stedi sandbox testing

Example transaction Bundle

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "resource": {
        "resourceType": "Patient",
        "name": [
          {
            "family": "Doe",
            "given": ["John"]
          }
        ],
        "birthDate": "1994-04-04"
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    },
    {
      "fullUrl": "urn:uuid:b2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
      "resource": {
        "resourceType": "Organization",
        "name": "Provider Name",
        "identifier": [
          {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "1999999984"
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Organization"
      }
    },
    {
      "fullUrl": "urn:uuid:c3e4f5a6-7b8c-4d9e-af1a-2b3c4d5e6f7a",
      "resource": {
        "resourceType": "Organization",
        "name": "Aetna",
        "identifier": [
          {
            "system": "https://www.stedi.com/healthcare/network",
            "value": "68069"
          }
        ],
        "type": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                "code": "ins",
                "display": "Insurance Company"
              }
            ]
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Organization"
      }
    },
    {
      "fullUrl": "urn:uuid:d4f5a6b7-8c9d-4e0f-b1a2-3c4d5e6f7a8b",
      "resource": {
        "resourceType": "Coverage",
        "status": "active",
        "subscriberId": "AMBETTER123",
        "subscriber": {
          "reference": "urn:uuid:a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
          "display": "John Doe"
        },
        "beneficiary": {
          "reference": "urn:uuid:a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
          "display": "John Doe"
        },
        "payor": [
          {
            "reference": "urn:uuid:c3e4f5a6-7b8c-4d9e-af1a-2b3c4d5e6f7a",
            "display": "Aetna"
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Coverage"
      }
    },
    {
      "fullUrl": "urn:uuid:e5a6b7c8-9d0e-4f1a-82b3-4d5e6f7a8b9c",
      "resource": {
        "resourceType": "CoverageEligibilityRequest",
        "status": "active",
        "purpose": ["benefits"],
        "patient": {
          "reference": "urn:uuid:a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
          "display": "John Doe"
        },
        "created": "2026-03-16",
        "provider": {
          "reference": "urn:uuid:b2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
          "display": "Provider Name"
        },
        "insurer": {
          "reference": "urn:uuid:c3e4f5a6-7b8c-4d9e-af1a-2b3c4d5e6f7a",
          "display": "Aetna"
        },
        "insurance": [
          {
            "coverage": {
              "reference": "urn:uuid:d4f5a6b7-8c9d-4e0f-b1a2-3c4d5e6f7a8b"
            },
            "focal": true
          }
        ],
        "item": [
          {
            "category": {
              "coding": [
                {
                  "system": "https://x12.org/codes/service-type-codes",
                  "code": "30",
                  "display": "Health Benefit Plan Coverage"
                }
              ]
            }
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "CoverageEligibilityRequest"
      }
    }
  ]
}

Receiving the Eligibility Response

After the eligibility check is sent, the Insurance Eligibility Bot will create and return a CoverageEligibilityResponse resource. This will reference all of the resources from the request.