Reference Data

Person-based membership discovery: which credit unions can I join?

The inverse of /v1/eligibility/check. Instead of a list of candidate credit unions, you supply the person — where they live or work, who they work for, their occupation or military affiliation, where they studied, and what they belong to — and the eligibility graph returns matching institutions bucketed by certainty.

At least one discriminating fact is required (home_zip, home_state, home_county, home_city, work_zip, work_state, work_county, work_city, occupation, employer, school, worship, military_status, associations, or willing_to_join_association: true); otherwise the honest answer would be "every credit union", which is not a search result. City facts require either their same-role state or a recognized same-role ZIP that uniquely identifies one state, and are accepted only when the closed Census gazetteer resolves them.

How it works: canonical geo keys, resolved organization ids, and bounded positive condition-kind scans NARROW to candidates; every candidate is then EVALUATED against its full rule set (never on the strength of the one condition that surfaced it), and results are BUCKETED. Credit unions with no graph rules yet fall back to the same annotation engine the rest of the API serves, marked engine: "legacy" per item. Candidate discovery is capped, so this result set is positive-evidence-only and non-exhaustive; absence from it never means ineligibility.

Never publishes ineligibility: a credit union whose held paths do not match is returned in unknown with an actionable unknown_reason. A web-derived rule set is open-world: failure to match it cannot prove that every membership path is absent.

The same capability ships as the MCP tool find_eligible_credit_unions.

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

post/v1/eligibility/search

Request

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

Request body

home_zipstring

US 5-digit home ZIP or ZIP+4. When home_state is also supplied, the ZIP crosswalk must agree with it.

home_statestring

2-letter US state code.

home_countystring

Home county. Wins over the ZIP-derived counties.

home_citystring

Census-recognized home city. Requires home_state or a recognized home_zip that uniquely identifies one state; unresolved place labels are rejected rather than guessed.

work_zipstring

US 5-digit work ZIP or ZIP+4. When work_state is also supplied, the ZIP crosswalk must agree with it.

work_statestring

2-letter state where the person works.

work_countystring

Work county. Wins over work-ZIP-derived counties.

work_citystring

Census-recognized city where the person works. Requires work_state or a recognized work_zip that uniquely identifies one state.

payroll_zipstring

US ZIP from which the employer issues payroll. When payroll_state is supplied, the ZIP crosswalk must agree with it.

payroll_statestring

2-letter state from which the employer issues payroll; distinct from work_state.

payroll_countystring

County from which the employer issues payroll; distinct from work_county.

payroll_citystring

Census-recognized city from which the employer issues payroll. Requires payroll_state or a recognized payroll_zip that uniquely identifies one state.

occupationstring

Occupation or trade for occupation/TIP membership paths.

employerstring

Employer, resolved to a canonical organization for SEG matching.

employer_org_idsstring[]

Caller-confirmed canonical employer ids from entity discovery. Every id is revalidated against a positive condition in the current active publication before use.

schoolstring

School, college, or university, resolved to a canonical organization.

school_org_idsstring[]

Caller-confirmed canonical school ids, revalidated against current active publications.

school_relationship'student' | 'alumni' | 'employee'

How the person relates to the school; required to affirm typed student, alumni, or school-employee graph paths.

associationsstring[]

Associations, unions, or member organizations the person ALREADY belongs to.

association_org_idsstring[]

Canonical ids for associations the person already belongs to. Selecting a discovered association does not itself confirm membership.

military_status'active_duty' | 'veteran' | 'reservist' | 'dod_civilian' | 'military_family'

Military affiliation, matched against military fields of membership.

worshipstring

Place of worship, resolved to a canonical organization.

worship_org_idsstring[]

Caller-confirmed canonical place-of-worship ids, revalidated against current active publications.

family_relationstring

How the user relates to a RELATIVE whose own affiliations may qualify them ('spouse', 'child', 'immediate family'). Required alongside the relative_* lists: without it there is nobody for those organizations to belong to. This answers SEG lead-ins of the form "Employees of the following companies AND THEIR IMMEDIATE FAMILIES are eligible".

relative_employersstring[]

Employers of the RELATIVE named by family_relation — not the user's own employer. Optional; omitted, a compound family door evaluates to unknown, never to a negative.

relative_employer_org_idsstring[]

Caller-confirmed canonical employers belonging to the relative named by family_relation.

relative_schoolsstring[]

Schools the RELATIVE named by family_relation attends. Same unknown-by-default contract as relative_employers.

relative_school_org_idsstring[]

Caller-confirmed canonical schools belonging to the relative named by family_relation.

relative_associationsstring[]

Associations the RELATIVE named by family_relation belongs to. Same unknown-by-default contract as relative_employers.

relative_association_org_idsstring[]

Caller-confirmed canonical associations belonging to the relative named by family_relation.

willing_to_join_associationboolean

When true, paths that require joining an association are treated as reachable and surface in conditionally_eligible with the cost and join URL when known.

property_zipstring

ZIP where the person OWNS REAL PROPERTY. A door of its own (migration 054): never inferred from where they live, and an absentee owner qualifies.

property_statestring

State where the person owns real property. Distinct from their home state.

property_countystring

County where the person owns real property. Distinct from their home county.

property_citystring

Census-recognized city where the person owns real property. Requires property_state or a recognized property_zip that uniquely identifies one state.

facility_zipstring

ZIP where the applicant's business maintains a location. Distinct from the worksite ZIP.

facility_statestring

State where the applicant's business maintains a location.

facility_countystring

County where the applicant's business maintains a location.

facility_citystring

Census-recognized city where the applicant's business maintains a location. Requires facility_state or a recognized facility_zip that uniquely identifies one state.

applicant_kind'person' | 'trust' | 'organization' | 'partnership' | 'corporation' | 'other_legal_entity'

What the applicant IS. Absent means a natural person, which is what every caller has always been. Some charters admit entities; a person is never rejected by an entity-only door, only left unknown.

military_service_statestring

The state the person serves, or served, in. A state-scoped military door ("Oklahoma National Guard") needs this; without it such a door reads unknown rather than eligible.

asserted_org_qualifiersstring[]

Narrowings the person asserts about themselves, quoted back from a missing_facts question (e.g. "assigned as Recruiters or ROTC Instructors within the State of Arkansas"). Absence CAPS a narrowed door at possibly_eligible rather than closing it.

limitinteger

Maximum entries returned PER BUCKET. Default 50.

Example request

{
  "home_zip": "28202",
  "home_state": "NC",
  "home_county": "Mecklenburg",
  "home_city": "Charlotte",
  "work_zip": "28208",
  "work_state": "NC",
  "work_county": "Mecklenburg",
  "work_city": "Charlotte",
  "payroll_zip": "79101",
  "payroll_state": "TX",
  "payroll_county": "Potter",
  "payroll_city": "Amarillo",
  "occupation": "nurse",
  "employer": "Bank of America",
  "school": "UNC Charlotte"
}

Response

Credit unions this person can join, bucketed by certainty. Evaluated non-matches remain visible in unknown; no web-derived record is published as ineligible.

candidates_evaluatedinteger required

How many credit unions were evaluated for this request.

candidate_limitinteger required

Hard cap on unique institutions admitted to this request's candidate set.

candidate_set_truncatedboolean required

True when the overall candidate cap or a bounded source scan was reached. The response is always non-exhaustive; true makes observed truncation explicit.

limitinteger required

Per-bucket cap actually applied.

engine'graph+legacy_fallback' required

Which engine produced the verdicts. Present when at least one result carried a graph verdict; the legacy annotation engine always runs and produces every legacy field.

disclosurestring required

Statement that must be shown to a consumer alongside this result.

missing_facts_truncatedboolean

True when a size cap dropped a question that could otherwise have been asked (3 per institution, 5 in the rollup, 20 unlock ids per rollup entry). The same honesty convention as candidate_set_truncated.

Example response

{
  "candidate_limit": 400,
  "resolved": {
    "geo_keys": [
      "state:NC",
      "county:NC:mecklenburg",
      "zip:28202"
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.