## Overview

The Stedi integration allows you to perform insurance eligibility checks by sending a a [CoverageEligibilityRequest](/content/docs/api/fhir/resources/coverageeligibilityrequest/index.html) resource and receiving a [CoverageEligibilityResponse](/content/docs/api/fhir/resources/coverageeligibilityresponse/index.html) resource with the benefits information. This workflow is handled by our **Insurance Eligibility Bot**. Please [contact the Medplum team](mailto:support@medplum.com) to get access to this bot.

For more general information about eligibility checks, please see our [Insurance Eligibility Checks](/content/docs/billing/insurance-eligibility-checks/index.html) 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**
  - **Organization (Provider)**
    - identifier:
      - system: http://hl7.org/fhir/sid/us-npi
      - value: 1999999984
  - **Patient (Subscriber)**
  - **Coverage (Insurance)**
    - subscriberId: AETNA12345
  - **Organization (Payer)**
    - identifier:
      - system: https://www.stedi.com/healthcare/network
      - value: 60054

### 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](/content/docs/api/fhir/operations/custom-operations/index.html) on `CoverageEligibilityRequest`.

### Sample FHIR API call
```http
POST {base}/fhir/R4/CoverageEligibilityRequest/{id}/$stedi-check-eligibility
```

### Stedi sandbox testing

#### Example transaction Bundle
```json
{
  "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](/content/docs/api/fhir/resources/coverageeligibilityresponse/index.html) resource. This will reference all of the resources from the request.