---
title: "Resolve organization labels to canonical eligibility graph ids"
method: POST
path: "/v1/eligibility/entities/resolve"
tags: ["Reference Data"]
---

# Resolve organization labels to canonical eligibility graph ids

`POST /v1/eligibility/entities/resolve`

## Request

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

Resolves only a unique normalized-exact match whose alias confidence is at least 0.8. Lower-confidence exact matches and prefixes remain suggestions, ambiguous exact matches remain ambiguous, and unresolved input never becomes a fact. Returned ids are revalidated against current publications by every person-evaluation surface.

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

## Request body

- object
  - `inputs` object[], required: Typed organization labels to resolve in stable caller order.
    - `value` string, required: Organization label exactly as supplied by the caller.
    - `entity_type` 'employer' | 'association' | 'school' | 'worship', required: Asserted organization category used to keep normalization type-safe.
  - `candidate_limit` integer: Maximum exact matches or non-authoritative prefix suggestions returned per input.

## Response `200`

Order-preserving exact resolutions and bounded suggestions.

- object
  - `results` object[], required: Resolution outcomes in the same order as the supplied inputs.
    - `input_index` integer, required: Zero-based position of the corresponding caller input.
    - `input` object, required: Normalized echo of the typed organization label supplied at this position.
    - `status` 'resolved' | 'ambiguous' | 'unresolved', required: Authoritative exact-resolution outcome; only one normalized-exact alias at confidence 0.8 or greater yields resolved and one selectable entity.
    - `entity` EligibilityEntity: A canonical organization referenced by at least one positive condition in a current active eligibility publication. This is an identity record, not proof of a person's relationship or eligibility.
      - `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.
    - `candidates` EligibilityEntity[], required: Bounded exact matches or prefix suggestions for caller confirmation.
      - `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.
    - `candidates_truncated` boolean, required: Whether additional candidates existed beyond candidate_limit.
  - `resolution_method` 'exact_normalized_only', required: Normalized-exact matching is required and its unique alias confidence must be at least 0.8 for authoritative canonical resolution.
  - `prefix_candidates_are_suggestions` unknown, required
  - `semantics` 'organization_resolution_not_eligibility', required: Entity resolution identifies an organization and never decides membership eligibility.
  - `disclosure` string, required: Required explanation of resolution authority and ambiguity.

## 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)