Provider eligibility is not Boolean. A provider does not simply qualify or fail — they may qualify, fail for a known reason, have missing required data, or not be subject to a constraint at all.
Orita uses four states for every constraint evaluation:
- matched — the provider meets the requirement
- failed — the provider does not meet the requirement
- unknown — required data is missing; the provider cannot be evaluated
- not_applicable — the constraint was not requested
Why Boolean eligibility is insufficient
A Boolean check produces two outcomes: eligible or ineligible. In a real provider network, a third outcome is critical: the data needed to evaluate the constraint does not exist.
If a platform requests licenseRegionCodes: { anyOf: ["US-NJ"] } and a provider has no license records at all, that provider is not the same as one who has a license in New York but not New Jersey. The first has unknown data. The second has known failing data.
Treating unknown as failed excludes providers that might qualify if their data were complete. Treating unknown as matched routes patients to providers whose eligibility has not been verified.
Orita routes providers with unknown required data to the manual review queue instead.
Availability states
Availability evaluation produces its own state set:
- verified_available — confirmed free via calendar
- unavailable — confirmed busy via calendar
- unverifiable — calendar connected but check failed
- stale — cached result older than threshold
- calendar_disconnected — no calendar connected
- not_checked — availability not yet evaluated
allowUnverifiable defaults to false. Calendar errors are never treated as free time.
Inspecting candidate decisions
Every resolution persists a per-provider eligibility record:
GET /api/v2/resolutions/{resolutionId}/candidates?status=excluded
Example excluded candidate:
{
"providerId": "pro_01K...",
"displayName": "Dr. Marcus Lee",
"eligibilityStatus": "excluded",
"exclusions": [
{
"code": "INSURANCE_NOT_ACCEPTED",
"field": "insurancePlanCodes",
"required": ["aetna"],
"actual": ["cigna"],
"sourceStatus": "verified"
}
],
"matchedConstraints": [
{ "code": "LICENSE_REGION_MATCH", "field": "licenseRegionCodes" }
]
}
Unknown data and manual review
Providers with unknown required data are:
- Excluded from resolution options
- Added to the manual review queue:
GET /api/v2/manual-review - Visible in candidates:
GET /api/v2/resolutions/:id/candidates?status=unknown
Resolve them by completing the provider's eligibility data in the provider graph, then re-running the resolution.
What AI agents must handle
An AI agent using Orita should never infer eligibility from free text. If a constraint returns unknown, the correct behavior is:
- Surface the unknown state to the operator
- Route to manual review or request updated provider data
- Do not assume the provider qualifies