Skip to main content

​
Overview

The Shasta Health Eligibility API lets you verify a patient’s insurance coverage programmatically. The flow is asynchronous: submit a check, then either poll the status endpoint or wait to receive a notification via webhook when the check completes.

​
Requirements

Before making your first eligibility check, complete these two setup steps.

​
1. Generate an API key

All requests to the Shasta Health Eligibility API must include an API key in the Authorization header. Follow the Authentication guide to generate a key and learn how to include it in requests.

​
2. Configure your webhook URL

To receive notifications via webhook when a check completes, go to Settings > API at app.shasta.health/provider/settings/api in the Shasta provider portal and enter your webhook URL in the Webhooks section. If you prefer to poll for results instead, you can skip this step. A signing secret lets you verify that webhook events are genuinely sent by Shasta Health.
  1. In the Webhooks section of Settings > API, click Edit on your webhook.
  2. Click the generate button next to the Signing Secret field to create a new secret, or enter your own.
  3. Copy the secret and store it securely — you will need it to verify incoming webhooks. You can always view or roll this secret from the webhook settings page.
Treat the signing secret like a password. Store it in an environment variable or secrets manager — never commit it to source control.

​
Step 1 — Submit an eligibility check

Send a POST request to /api/eligibility with the provider, subscriber, and trading partner information.

​
Request

curl -X POST https://app.shasta.health/api/eligibility \
  -H "Authorization: Key $SHASTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tradingPartnerServiceId": "60054",
    "provider": {
      "organizationName": "Shasta Medical Group",
      "npi": "1234567890"
    },
    "subscriber": {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "19800115",
      "memberId": "XYZ123456"
    },
    "encounter": {
      "serviceTypeCodes": ["30"],
      "dateOfService": "20260301"
    }
  }'

​
Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "IN_PROGRESS"
}
Save the id — you can use it to GET the eligibility check status and results once complete.

​
Step 2 — Webhook notification

This is the recommended way to receive eligibility results.
When the eligibility check finishes processing, Shasta sends a single POST request to your configured webhook URL. The webhook fires exactly once per check, and the status in the payload will always be either COMPLETED or FAILED — it will never fire while the check is still in progress. The payload uses the same schema as the GET /api/eligibility/{id}/status response.

​
Webhook configuration

The webhook URL and signing secret are configured during the Requirements step above. You do not pass a webhook URL in the API request.

​
Webhook headers

Every webhook request includes the following headers:
HeaderDescription
X-Webhook-TimestampUnix timestamp (seconds) of when the request was sent.
X-Webhook-SignatureHMAC-SHA256 hex digest of the request. Only present when a signing secret is configured.

​
Verifying the webhook signature

If you configured a signing secret, each webhook request will include an X-Webhook-Signature header. To verify it, compute the expected signature and compare:
  1. Read the X-Webhook-Timestamp header and the raw request body.
  2. Concatenate them as {timestamp}.{body}.
  3. Compute the HMAC-SHA256 hex digest using your signing secret.
  4. Compare the result to the X-Webhook-Signature header value using a constant-time comparison.
import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhookSignature(
  body: string,
  timestamp: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
To protect against replay attacks, also verify that the X-Webhook-Timestamp is within a reasonable window (e.g. 5 minutes) of the current time.

​
Webhook payload

The webhook body is a JSON object with the same EligibilityCheckResponse schema: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "payer": {
    "payerName": "Aetna",
    "payerId": "60054"
  },
  "subscriber": {
    "firstName": "Jane",
    "lastName": "Doe",
    "memberId": "XYZ123456",
    "dateOfBirth": "19800115"
  },
  "benefitsInformation": [
    {
      "code": "1",
      "name": "Active Coverage",
      "coverageLevel": "Individual",
      "serviceTypeCodes": ["30"],
      "serviceTypes": ["Health Benefit Plan Coverage"],
      "inPlanNetworkIndicator": "Yes",
      "insuranceType": "Preferred Provider Organization"
    }
  ],
  "planInformation": {
    "planName": "PPO Gold Plan"
  },
  "planDateInformation": {
    "eligibility": "20250101",
    "plan": "20250101"
  },
  "tradingPartnerServiceId": "60054"
}
Your endpoint should return a 200 status code to acknowledge receipt.

​
Handling failures

If the check fails, the webhook payload will have "status": "FAILED" and an errors array: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "FAILED",
  "errors": [
    {
      "code": "71",
      "description": "Patient Birth Date Does Not Match That for the Patient on the Database",
      "followupAction": "Correct and Resubmit"
    }
  ]
}

​
Step 3 — Retrieve an eligibility result (optional)

Use GET /api/eligibility/{id}/status to check the processing status and get results once the check is complete.

​
Request

curl https://app.shasta.health/api/eligibility/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
  -H "Authorization: Key $SHASTA_API_KEY"

​
While processing

While the check is still running, the response contains only id and status: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "IN_PROGRESS"
}

​
When complete

Once the check finishes, the full eligibility response is returned: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "payer": {
    "payerName": "Aetna",
    "payerId": "60054"
  },
  "subscriber": {
    "firstName": "Jane",
    "lastName": "Doe",
    "memberId": "XYZ123456",
    "dateOfBirth": "19800115"
  },
  "benefitsInformation": [
    {
      "code": "1",
      "name": "Active Coverage",
      "coverageLevel": "Individual",
      "serviceTypeCodes": ["30"],
      "serviceTypes": ["Health Benefit Plan Coverage"],
      "inPlanNetworkIndicator": "Yes",
      "insuranceType": "Preferred Provider Organization"
    }
  ],
  "planInformation": {
    "planName": "PPO Gold Plan"
  },
  "planDateInformation": {
    "eligibility": "20250101",
    "plan": "20250101"
  },
  "tradingPartnerServiceId": "60054"
}
If the check failed, status will be FAILED and the errors array will contain details.
Most checks complete within 10 minutes. If you have a webhook configured, you can skip polling entirely and wait for the webhook notification.

​
Status values

StatusDescription
IN_PROGRESSThe eligibility check is still being processed.
COMPLETEDThe check finished successfully. Full results are available.
FAILEDThe check encountered an error. See the errors array for details.

​
Next steps

See the API Reference for full schema details on all request and response fields.