Retrieve Batch Check Statuses

Retrieve status information for all eligibility checks within a batch, regardless of processing status

GET /eligibility-manager/batch/{batchId}/items

This endpoint retrieves the processing status and other summary information for all of the eligibility checks in the specified batch. It doesn't include the complete eligibility response. For the full results of each eligibility check, call the Poll Batch Checks endpoint instead.

You can use this endpoint to determine whether specific eligibility checks within a batch have completed. You can also use the response to determine whether patients have active or inactive coverage without having to poll.

1. Call this endpoint with the batch ID for the eligibility check batch. This is the batchId Stedi returned in the Batch Eligibility Checks endpoint response. It's also available on the batch's details page in the Stedi portal.
2. Stedi returns information about the processing status of each eligibility check within the batch, including whether the check completed successfully and information about the patient's coverage status (eligibilitySearchStatus). Each item in the response corresponds to one eligibility check within the batch.

Visit Retrieve batch results for a complete how-to guide.

Authorizations

Authorization · string · required · header

A Stedi API Key for authentication.

Path Parameters

batchId · string

The unique identifier for the batch. This is the batchId returned in the Batch Eligibility Check endpoint response. It's also listed as the Batch ID in the Stedi portal.

Query Parameters

pageSize · number

The maximum number of elements to return in a page. If not specified, the default is 100.

• Range: ≥ 1 and ≤ 1000

pageToken · string

A token returned by a previous call to this operation in the nextPageToken property. You can use it to retrieve the next page of results. If no pageToken is included in the request, Stedi returns the first page of results.

• Required string length: 1 - 1024

Response

application/json

GetBatchItems 200 response

items · array<object>

A list of batch items. Each item represents a single eligibility check in the batch. Unlike the polling endpoint, which only returns results for completed eligibility checks, this endpoint returns results for all eligibility checks in the batch, regardless of their processing status.

All batch items may not be returned in a single response; use the nextPageToken to retrieve subsequent pages of results.

items[]. additionalInfo · eligibility

Additional information about the eligibility check.

items[].additionalInfo. eligibility · object · required

Additional information specific to eligibility batch items.

items[].additionalInfo.eligibility. aaaErrors · array<object>

When a payer rejects your eligibility check, the response contains one or more AAA errors that specify the reasons for the rejection and any recommended follow-up actions.

Any errors that occur at the payer, provider, subscriber, or dependents levels are also included in this array, allowing you to review all errors in a central location. If there are no AAA errors, this array will be empty.

items[].additionalInfo.eligibility.aaaErrors[]. code · string

The error code. Visit Eligibility troubleshooting for a complete list of all possible error codes and descriptions.

Payers may sometimes return other non-compliant values.

Possible values

04

15

33

35

41

items[].additionalInfo.eligibility.aaaErrors[]. description · string

The error description.

items[].additionalInfo.eligibility.aaaErrors[]. field · string

The error type, AAA.

items[].additionalInfo.eligibility.aaaErrors[]. followupAction · string

Allowed actions you can take, based on the rejection reason code. For example Please Correct and Resubmit.

Payers may sometimes return other non-compliant values.

Possible values

Please Correct and Resubmit

Resubmission Not Allowed

Please Resubmit Original Transaction

Resubmission Allowed

Do Not Resubmit; Inquiry Initiated to a Third Party

items[].additionalInfo.eligibility.aaaErrors[]. location · string

The location of the error within the original X12 EDI response.

items[].additionalInfo.eligibility.aaaErrors[]. possibleResolutions · string

Information to help you correct the error.

We periodically update this guidance, so these strings may change at any time and may differ between eligibility responses. Don't build programmatic logic that depends on matching these strings exactly.

items[].additionalInfo.eligibility. eligibilitySearchId · string

The eligibility search ID for this eligibility check. This is an identifier that allows Stedi to group eligibility checks for the same patient into a unified record within Eligibility Manager called an eligibility search.

This property is for use by Stedi tools only, such as Stedi's MCP server.

items[].additionalInfo.eligibility. eligibilitySearchStatus · string

The status of the eligibility check. Can be:

• queued: Stedi placed the eligibility check in its internal queue and will send it to the payer when resources are available. This status is common when you schedule batch eligibility check refreshes through the API or perform large bulk retries that exceed your account's concurrency budget. You can typically expect the status to change to Started within a few seconds.
• started: Stedi has sent the eligibility check to the payer and is waiting for a response.
• failed: The payer returned an error code in the response. Review the error code and retry the eligibility check.
• inactive: The payer's response doesn't contain an active eligibility and benefit type. This means that the patient doesn't have active coverage for the requested services.
• active: The payer's response contains an active eligibility and benefit type. This means that the patient has active coverage for at least some services.

Possible values

active

failed

inactive

started

queued

items[].additionalInfo.eligibility. outboundTraceId · string

A unique Stedi-generated identifier for the eligibility check. It's required for the generated X12 EDI transaction Stedi sends to payers. This identifier is different from the requestId and the submitterTransactionIdentifier.

• You can use this identifier to find an eligibility check in the Stedi portal. Click Find by ID in the navigation bar and enter the outboundTraceId to go directly to the eligibility check's details page.
• Don't use this ID to correlate eligibility check requests and responses. Use the submitterTransactionIdentifier property for correlation and tracking instead.

items[].additionalInfo.eligibility. payerId · string

The payer ID for this eligibility check.

items[].additionalInfo.eligibility. providerName · string

The provider's name as provided in the eligibility check.

items[].additionalInfo.eligibility. providerNpi · string

The provider's NPI as provided in the eligibility check.

• Pattern: ^\d{10}$

items[].additionalInfo.eligibility. submitterTransactionIdentifier · string

The unique identifier you assigned to the eligibility check when you submitted the batch. Stedi also returns this identifier in the Poll Batch Eligibility Checks endpoint response, allowing you to correlate eligibility check requests and responses.

items[].additionalInfo.eligibility. subscriberFirstName · string

The subscriber's first name as provided in the eligibility check.

items[].additionalInfo.eligibility. subscriberLastName · string

The subscriber's last name as provided in the eligibility check.

items[].additionalInfo.eligibility. subscriberMemberId · string

The subscriber's member ID as provided in the eligibility check.

items[]. batchId · string · required

The ID for the batch containing this eligibility check.

items[]. createdAt · string · required

The date and time when the eligibility check was created.

• Format: date-time

items[]. index · number

Only relevant for batches submitted through the JSON API. This is the index of the item in the batch. It starts at 0.

items[]. requestId · string

A globally unique identifier for this eligibility check within Stedi. Stedi uses this identifier to construct the URL for the eligibility check's detail pages within the Stedi portal.

Don't use this ID to correlate eligibility check requests and responses. Use the additionalInfo.eligibility.submitterTransactionIdentifier property for correlation and tracking instead.

items[]. rowNumber · number

Only relevant for batches submitted through CSV upload. This is the row number for this eligibility check in the CSV file. It starts at 2 because the first row of the CSV file is the header.

items[]. state · string · required

The current state of the eligibility check. Can be:

• PENDING: Stedi hasn't begun processing the eligibility check.
• VALIDATED: Stedi finished validating the eligibility check and is ready to execute it.
• VALIDATION_FAILED: Stedi found errors in the eligibility check that you need to fix before processing can continue. This is typically due to malformed CSV data, missing required fields, or invalid values.
• STARTED: Stedi has begun processing the eligibility check.
• RETRYING: Stedi is retrying the eligibility check. Stedi retries eligibility checks that fail due to payer connectivity issues for up to 8 hours.
• COMPLETED: Stedi successfully processed the eligibility check and received a response from the payer. This doesn't indicate that the payer has active coverage, only that Stedi was able to get a response.
• COMPLETED_WITH_ERRORS: Stedi finished processing the eligibility check, but couldn't get a response from the payer. A common reason for failure is payer connectivity issues.

Possible values

PENDING

VALIDATED

VALIDATION_FAILED

STARTED

RETRYING

items[]. updatedAt · string · required

The date and time when the eligibility check was last updated.

• Format: date-time

nextPageToken · string

Token for pagination to retrieve the next page of results; null if there are no more results

• Required string length: 1 - 1024

cURL

curl --request GET \
  --url "https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch/{batchId}/items" \
  --header "Authorization: <api_key>"

JavaScript

fetch("https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch/{batchId}/items", {
  headers: {
    "Authorization": "<api_key>"
  }
})

Go

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch/{batchId}/items"

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", "<api_key>")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

Python

import requests

url = "https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch/{batchId}/items"

response = requests.request("GET", url, headers = {
  "Authorization": "<api_key>"
})

print(response.text)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;

HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://manager.us.stedi.com/2024-04-01/eligibility-manager/batch/{batchId}/items"))
  .header("Authorization", "<api_key>")
  .GET()
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

200

{
  "items": [
    {
      "additionalInfo": {
        "eligibility": {
          "eligibilitySearchId": "01932c61-2d4f-7d22-85fa-c7db2e13e771",
          "eligibilitySearchStatus": "active",
          "payerId": "BCBS",
          "submitterTransactionIdentifier": "ABC123456789",
          "subscriberFirstName": "John",
          "subscriberLastName": "Doe",
          "subscriberMemberId": "123456789"
        }
      },
      "batchId": "01932c61-2d4f-7d22-85fa-c7db2e13e771",
      "createdAt": "2025-03-31T14:25:30Z",
      "requestId": "req-01a2b3c4-d5e6-7f89-0123-456789abcdef",
      "rowNumber": 1,
      "state": "COMPLETED",
      "updatedAt": "2025-03-31T14:26:45Z"
    },
    {
      "additionalInfo": {
        "eligibility": {
          "eligibilitySearchId": "01932c61-2d4f-7d22-85fa-c7db2e13e772",
          "eligibilitySearchStatus": "failed",
          "payerId": "AETNA",
          "submitterTransactionIdentifier": "GHJ987654321",
          "subscriberFirstName": "Jane",
          "subscriberLastName": "Smith",
          "subscriberMemberId": "987654321"
        }
      },
      "batchId": "01932c61-2d4f-7d22-85fa-c7db2e13e771",
      "createdAt": "2025-03-31T14:25:30Z",
      "requestId": "req-02a2b3c4-d5e6-7f89-0123-456789abcdef",
      "rowNumber": 2,
      "state": "COMPLETED_WITH_ERRORS",
      "updatedAt": "2025-03-31T14:27:15Z"
    }
  ],
  "nextPageToken": "945ff6de213d3ef481d028065d4c12fb996a166a3a90ef98564318decfae50ce4b36d74b7e9d9bafa6e1d169"
}

400

{
  "fieldList": [
    {
      "message": "string",
      "path": "string"
    }
  ],
  "message": "string"
}

401

{
  "code": "string",
  "message": "string"
}

403

{
  "code": "string",
  "message": "string"
}

404

{
  "code": "string",
  "message": "string"
}

500

{
  "code": "string",
  "message": "string"
}