Reference Data

Turn a person's own words into person-fact fields, for confirmation

This is an extractor, not a decision. Prose in, the structured facts /v1/eligibility/search accepts out, each with the exact words we read it from and a flag saying whether a human should confirm it. The response contains no status, no bucket, no credit union and no URL, and it cannot be made to contain one: there is no property in the response schema in which a verdict could be returned.

The intended flow is two calls. Send the person's sentence here; show them what we read; then send person_search_body - plus whatever they confirmed - to POST /v1/eligibility/search, where the deterministic eligibility graph decides, exactly as it does today.

How the model is contained. Its only output channel is a closed enum of field names generated from the search endpoint's own schema, a raw string this API coerces itself, and an evidence quote that must appear verbatim in your text. A quote we cannot find in your text means the fact is dropped. The worst case for hostile prose in text is therefore a WRONG FACT, flagged for confirmation - never an assertion about a credit union.

Privacy. text is never stored: not in usage logs, not in object storage, not in an error payload. Logs carry a truncated hash of it, its length, and the NAMES of the fields extracted - never values. Responses are Cache-Control: no-store.

Cost. Billed as 3 API units per call, because one model call is roughly three times the marginal cost of a deterministic lookup. This is an Enterprise Routes operation. It is separately capped at 20 calls per key per rolling hour to bound inference spend against a looping agent; that cap is independent of your plan quota and returns 429 with scope: "endpoint_burst".

Failure is always silent about eligibility. If extraction is unavailable you get 503 with facts: []. Ask the person for the fields directly; never read a failure as a negative answer.

post/v1/eligibility/facts

Request

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

Request body

textstring required

The person's own words, 1-2000 characters after trimming. Send it VERBATIM - do not paraphrase or pre-structure it, because evidence spans are anchored in the original sentence. Over the limit returns 400 rather than truncating: a cut final clause silently deletes a membership door.

known_factsobject

Optional. Facts you already hold, in the same shape as the /v1/eligibility/search request body. Echoed with source="supplied" and never overwritten; an extracted value that contradicts one is returned alongside it with conflict_with set.

locale'en-US'

Optional. Only "en-US" is supported at launch.

Example request

{
  "text": "I'm a nurse at a hospital in Tulsa, live in Broken Arrow, and my late father was a TTCU member",
  "known_facts": {
    "home_state": "OK"
  }
}

Response

Facts read from the text, for confirmation.

person_search_bodyobject

A ready-to-POST request body for /v1/eligibility/search, containing ONLY facts with needs_confirmation=false and confidence at or above 0.8, plus everything you supplied. Facts awaiting confirmation are deliberately excluded; add them once the person says yes.

confirmation_requiredboolean

True when any fact needs confirmation or any unparsed span exists. When true, show the facts to the person before calling /v1/eligibility/search.

confidence_is_model_self_reportedboolean

Always true. A standing warning that confidence is the extraction model's own uncalibrated number rather than a measured accuracy, so a consumer UI can hide the figure and show the evidence quote instead.

modelstring

Extraction model identifier.

extractor_versionstring

Version of this extractor's prompt and post-processing.

notestring

Standing disclosure: these are our reading of what the person said, not a membership decision.

billed_unitsinteger

API units billed for this call: 3 for a live extraction, 0 for a sandbox fixture.

sandboxboolean

Present and true only for a sandbox (rk_test_…) key, which receives a frozen fixture extraction: no model call, no inference spend, and billed_units: 0. The shape is otherwise identical to a live extraction.

Changes

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