/api/eligibility/check

Run a live real-time insurance eligibility check against the payer network. Deducts one check from your wallet.

POST

JSON body (recommended)

Headers

Header	Required	Description
Authorization	✓	Bearer <workspace_api_key>
X-Client-Id	✓	UUID of the clinic making the request
Content-Type	✓	application/json
Idempotency-Key	—	UUID. Retrying with the same key returns the cached response instead of a new check.

Request body

Field	Type	Required	Description
payerName	string	✓	Insurance company name. Case-insensitive fuzzy match against the payer catalog (e.g. "Aetna", "UnitedHealthcare", "BCBS Texas").
memberId	string	✓	Insurance member ID.
patientFirstName	string	✓	Patient first name.
patientLastName	string	✓	Patient last name.
patientDateOfBirth	string	—	ISO 8601 (YYYY-MM-DD) or MM/DD/YYYY. Recommended — some payers require it.

curl -X POST https://eligibility.dev/api/eligibility/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "payerName": "Cigna",
    "memberId": "U123456789",
    "patientFirstName": "John",
    "patientLastName": "Doe",
    "patientDateOfBirth": "1990-06-15"
  }'

GET

Query-string (voice AI / no-body integrations)

Identical behavior to POST, but all parameters are URL query strings. Designed for tools that cannot send a request body — for example Voice AI webhooks or CRM automations. Use POST when you can; GET exposes patient data in server logs and browser history.

Query parameters

Parameter	Required	Description
payerName	✓	Insurance company name.
memberId	✓	Insurance member ID.
patientFirstName	✓	Patient first name.
patientLastName	✓	Patient last name.
patientDateOfBirth	—	ISO 8601 (YYYY-MM-DD) or MM/DD/YYYY.
idempotencyKey	—	UUID for idempotent retries (alternative to the Idempotency-Key header).

Headers

Header	Required	Description
Authorization	✓	`Bearer YOUR_API_KEY`
X-Client-Id	✓	UUID of the clinic making the request

curl "https://eligibility.dev/api/eligibility/check?payerName=Aetna&memberId=W123456789&patientFirstName=Jane&patientLastName=Smith&patientDateOfBirth=1985-03-22" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Client-Id: YOUR_CLIENT_ID"

Response

Always HTTP 200 for both successful and upstream-error outcomes. Read success first to branch your logic.

Field	Type	Description
success	boolean	true = coverage confirmed; false = upstream error or coverage not active.
benefitSummary.coverageActive	boolean	Whether coverage is currently active.
benefitSummary.planName	string \| null	Name of the insurance plan.
benefitSummary.payerName	string \| null	Payer name as returned by the clearinghouse.
benefitSummary.deductibleRemaining	number \| null	Remaining deductible in USD.
benefitSummary.outOfPocketRemaining	number \| null	Remaining out-of-pocket maximum in USD.
benefitSummary.coinsurancePercent	number \| null	Patient coinsurance percentage (e.g. 20 = 20%).
benefitSummary.copayAmount	number \| null	Copay amount in USD.
benefitSummary.inNetworkPreferred	boolean \| null	Whether in-network benefits apply.
traceId	string \| null	Clearinghouse trace ID. Include in support requests.
upstreamStatusCode	number	HTTP status returned by the clearinghouse.
latencyMs	number	Total request latency in milliseconds.
errorMessage	string \| null	Human-readable upstream error message. null when success is true.

Example responses

Successful check (HTTP 200)

{
  "success": true,
  "benefitSummary": {
    "coverageActive": true,
    "planName": "Cigna Open Access Plus",
    "payerName": "Cigna",
    "deductibleRemaining": 1200.00,
    "outOfPocketRemaining": 3500.00,
    "coinsurancePercent": 20,
    "copayAmount": 25,
    "inNetworkPreferred": true
  },
  "traceId": "stedi-abc123xyz",
  "upstreamStatusCode": 200,
  "latencyMs": 487,
  "errorMessage": null
}

Upstream error — subscriber not found (HTTP 200, success: false)

{
  "success": false,
  "benefitSummary": {
    "coverageActive": false,
    "planName": null,
    "payerName": "Cigna",
    "deductibleRemaining": null,
    "outOfPocketRemaining": null,
    "coinsurancePercent": null,
    "copayAmount": null,
    "inNetworkPreferred": null
  },
  "traceId": "stedi-xyz789abc",
  "upstreamStatusCode": 404,
  "latencyMs": 210,
  "errorMessage": "Subscriber not found"
}

Note: upstream payer errors (subscriber not found, payer unavailable) return HTTP 200 with success: false. HTTP 4xx/5xx errors indicate API-level issues (auth, validation, rate limits). See error codes.