Eligibility & benefits | Kairos API Docs

Request

Send one subscriber, one insurance, the requesting provider, and the service date and X12 service type codes to check. Use service type code 30 for plan-level benefits.

{
  "subscriber": {
    "external_id": "patient-456",
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1980-03-04"
  },
  "insurance": {
    "payer_name": "Aetna",
    "member_id": "ABC123",
    "group_number": null,
    "patient_name": {
      "first_name": "Jane",
      "last_name": "Smith"
    }
  },
  "provider": {
    "npi": "1234567893"
  },
  "service": {
    "date_of_service": "2026-09-09",
    "service_type_codes": ["30"]
  }
}

Request fields

Field	Required	Description
`subscriber.external_id`	Yes	Patient identifier from your system.
`subscriber.first_name`	Yes	Subscriber first name.
`subscriber.last_name`	Yes	Subscriber last name.
`subscriber.date_of_birth`	Yes	Valid calendar date in `YYYY-MM-DD` format.
`insurance.payer_name`	Yes	Insurance company name shown on the card.
`insurance.member_id`	Yes	Member ID shown on the card. Preserve letters, dashes, and leading zeros.
`insurance.group_number`	No	Plan group number, as a string or `null`.
`insurance.patient_name`	No	Name printed on the insurance card when it differs from the subscriber name. Include both first and last name.
`provider.npi`	Yes	Ten-digit NPI with a valid check digit.
`service.date_of_service`	Yes	Service date in `YYYY-MM-DD` format.
`service.service_type_codes`	Yes	Nonempty array of X12 service type codes.

insurance is one object, not an array. If patient_name is present, that name is sent to the payer while date of birth and external ID continue to come from the subscriber.

Response

A completed inquiry returns the common response below. Project-specific integrations may append fields, but the common sections remain available. The example abbreviates raw_response.

{
  "request_id": "59462879-481d-4724-b4c8-b257023e91f1",
  "payer": { "id": "60054", "name": "Aetna" },
  "status": "completed",
  "coverage": {
    "isCovered": true,
    "statusCode": "1",
    "statusLabel": "Active Coverage",
    "planName": "Example PPO",
    "insuranceType": "Preferred Provider Organization",
    "insuranceTypeCode": "PR",
    "planBegin": "2026-01-01",
    "planEnd": null,
    "eligibilityBegin": "2026-01-01",
    "verificationDate": "2026-09-09",
    "confidence": "high"
  },
  "deductible": {
    "inNetwork": {
      "individual": { "total": 1000, "met": 400 },
      "family": null
    },
    "outOfNetwork": null,
    "networkTiering": "unknown",
    "confidence": "high"
  },
  "outOfPocket": {
    "inNetwork": {
      "individual": { "max": 5000, "met": 1500 },
      "family": null
    },
    "outOfNetwork": null,
    "networkTiering": "unknown",
    "confidence": "high"
  },
  "costShare": {
    "inNetwork": {
      "copay": 25,
      "patientCoinsurancePercent": 20,
      "copayRows": [
        {
          "amount": 25,
          "descriptions": [],
          "coverageLevel": "IND",
          "period": "Visit"
        }
      ],
      "coinsuranceRows": [
        {
          "patientPercent": 20,
          "descriptions": [],
          "coverageLevel": "IND",
          "period": "Visit"
        }
      ]
    },
    "outOfNetwork": null,
    "networkTiering": "unknown"
  },
  "raw_response": {
    "benefitsInformation": []
  },
  "error": null
}

Response fields

Field group	Meaning
`request_id`	Identifier to log and provide when contacting support.
`payer`	Canonical payer selected from the submitted payer name.
`status`	`completed` when the payer inquiry completed and `failed` when it did not. Read `coverage.isCovered` for coverage status.
`coverage`	Overall coverage status, plan details, payer-reported dates, verification date, and confidence.
`deductible`	Overall individual and family deductible totals and met amounts by network.
`outOfPocket`	Overall individual and family out-of-pocket maximums and met amounts by network.
`costShare`	Overall copay and patient coinsurance by network, with normalized supporting rows.
`raw_response`	Payer response used to build the normalized sections.
`error`	Stable error code, readable message, and retry guidance when the request fails.

Interpretation

status: "completed" means the inquiry completed. It does not mean coverage is active.
Missing information remains null. A zero means the payer reported or safely implied zero.
Deductible, out-of-pocket, copay, and coinsurance use overall service type 30 evidence.
patientCoinsurancePercent: 20 means the patient is responsible for 20 percent.
networkTiering describes the returned benefits. It does not prove that a provider is in network.
Eligibility information is not a guarantee of payment or authorization.

Errors

Failed payer inquiries use the same response envelope, with normalized benefit sections set to null. Retry only when error.retriable is true.

{
  "request_id": "5d91952a-6a50-4498-b531-38d94046128a",
  "payer": null,
  "status": "failed",
  "coverage": null,
  "deductible": null,
  "outOfPocket": null,
  "costShare": null,
  "raw_response": null,
  "error": {
    "code": "PAYER_NOT_RECOGNIZED",
    "message": "Payer could not be resolved for eligibility.",
    "retriable": false
  }
}

Code	HTTP	Retriable	Meaning
`MISSING_API_KEY`	`401`	No	No API key was sent.
`INVALID_API_KEY`	`401`	No	The API key is invalid, revoked, or unsupported.
`VALIDATION_ERROR`	`400`	No	The request body is invalid.
`PAYER_NOT_RECOGNIZED`	`200`	No	The payer name could not be resolved.
`PATIENT_NOT_FOUND`	`200`	No	The payer could not identify the member.
`ELIGIBILITY_REJECTED`	`200`	No	The payer rejected the eligibility inquiry.
`NETWORK_ERROR`	`200`	Yes	The payer or network dependency failed temporarily.
`INTERNAL_ERROR`	`500`	Yes	An unexpected Kairos-side failure occurred.

Environments

Keys beginning with sk_test_ use deterministic sandbox fixtures and do not call a payer. Keys beginning with sk_live_ perform live payer resolution and eligibility checks. Kairos issues keys for a specific project and environment during onboarding.

Explore the Kairos API

Verify eligibility