---
title: "Browse or search canonical eligibility organizations"
method: POST
path: "/v1/eligibility/entities/search"
tags: ["Reference Data"]
---

# Browse or search canonical eligibility organizations

`POST /v1/eligibility/entities/search`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/v1/eligibility/entities/search`
- Auth: API key in header `X-API-Key`

Browses or searches only organizations named by positive conditions in current active eligibility publications. Omit `query` to retrieve the most connected organizations for the requested types; this browse order reflects graph connectivity, not popularity, quality, or a recommendation. Results are organization identities for caller confirmation—not proof that the person has the relationship and not an eligibility verdict. Queries are private, never body-logged, and returned with `Cache-Control: no-store`.

**Authentication required**: Pass your API key in the `X-API-Key` header.

## Request body

- object
  - `query` string: Optional organization name or prefix. Omit to browse the most connected active-publication organizations for the requested types.
  - `types` string[]: Optional organization types to search; omitting it searches all supported types.
  - `limit` integer: Maximum ranked entities returned for this bounded query.

## Response `200`

Bounded canonical organizations ranked by normalized exact/prefix match for search, or active-publication connectivity for browse.

- EligibilityEntitySearchResponse: Bounded active-publication entity discovery result. A match identifies an organization for caller confirmation and never proves a relationship or eligibility.
  - `query` string, nullable, required: Caller query returned for this no-store response, or null in browse mode.
  - `normalized_query` string, nullable, required: Normalized comparison key used for exact and prefix search, or null in browse mode.
  - `query_truncated` unknown, required
  - `result_mode` 'search' | 'most_connected', required: Whether results follow text-match ranking or query-less graph-connectivity ranking. Most-connected is not a popularity or recommendation signal.
  - `types` string[], required: Organization types searched by this request.
  - `results` EligibilityEntity[], required: Ranked canonical entities backed by positive conditions in active publications.
    - `entity_id` string, required: Canonical graph entity identifier; identical to org_id.
    - `org_id` string, required: Stable value accepted by the matching person *_org_ids field.
    - `canonical_name` string, required: Display name retained for this canonical organization.
    - `entity_type` 'employer' | 'association' | 'school' | 'worship', required: Organization category and corresponding person-fact namespace.
    - `matched_alias` string, nullable, required: Stored alias that matched the query, or null when the canonical name matched.
    - `match_method` 'normalized_exact' | 'normalized_prefix' | 'canonical_id', required: Normalization route that produced this result.
    - `match_confidence` number, required: Confidence in the search match only, distinct from eligibility-rule confidence.
    - `active_rule_count` integer, required: Positive conditions in active publications that reference this entity.
    - `active_institution_count` integer, required: Distinct active-publication institutions that reference this entity.
    - `last_confirmed_at` string, date-time, nullable, required: Most recent confirmation time among active conditions, when available.
  - `result_limit` integer, required: Bound applied to the visible result list.
  - `results_truncated` boolean, required: Whether more ranked matches existed beyond result_limit.
  - `semantics` 'organization_discovery_not_eligibility', required: Explicit guard that discovery is not a membership decision.
  - `disclosure` string, required: Required explanation of confirmation, evidence, and eligibility boundaries.

## Other responses

- `400`: The request was malformed — a missing required field, an unparseable body, or a parameter outside its allowed range. The `error` field names what was wrong; retrying the identical request will fail identically.
- `401`: No API key, or a key that is unknown or disabled. Send it in the `X-API-Key` header. Free keys are issued instantly by POST /keys with an email address. The response carries `WWW-Authenticate` pointing at this host's protected-resource metadata, and the `RateLimit-*` headers describing the Free-tier budget a key issued now would carry (scope `anonymous`) — a rejected request spends none of it, so `Remaining` equals `Limit`.
- `402`: The key is valid, but RateAPI Routes is available only on Enterprise. The response includes `required_plan`, `upgrade_url`, and a `Link` header with `rel="upgrade"`; the rejected request does not consume quota.
- `429`: Quota exhausted for the current window. `Retry-After` gives the seconds to wait; `upgradeInfo` explains how to lift the cap. Retrying before the reset will fail again and still counts as a request.

---

[API](https://skmtc.dev/rateapi/apis/rate-api.md) · [All operations](https://skmtc.dev/rateapi/apis/rate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rateapi/apis/rate-api/revisions/06a6db76995f?raw)