# resolve_entity

Resolve Entity · v2.0.0 · curated

Resolve any company name or ID to Vlada's canonical entity: a legal entity (le:...), a brand, an NAIC group, a CMS contract (H1234), a plan (H1234-001@2027), a Medicaid plan, a Marketplace issuer (HIOS). Matches exactly on IDs, EIN, NAIC code, CIK and names, then on names that contain every word of the text (returned as candidates, never as a match). Pass on=YYYY-MM-DD to match names as of a date. Then call describe_entity with the entity_id for its owners on a date, what it holds, and its events.

**Inputs.**
- `text` (required): 
- `on`: 
- `limit`: 

**Known limits.**
- Layer one only: no facilities, doctors, networks or PBMs (layers two to five follow on Ben's signature).
- About 16% of Medicare Advantage members sit under a chain with one hop resting on CMS's parent string alone (grade B); the top parent is not in doubt, the corroborating filing is not yet attached.
- Belief time (what an earlier build served) is not yet queryable; every answer carries the build it was read from.
- The 233 open review-queue rows (candidate contract transfers) are not served.

**A real answer** (customer seat, 3.98 s, args `{"text":"Humana Inc."}`):

```json
{
 "value": {
  "found": true,
  "status": "found",
  "not_found_reason": null,
  "query": {
   "text": "Humana Inc.",
   "on": null
  },
  "candidates": [
   {
    "entity_id": "le:000009",
    "kind": "legal_entity",
    "label": "Humana Inc.",
    "matched_on": [
     "name=Humana Inc.",
     "label=Humana Inc."
    ],
    "score": 1.0,
    "redirect_from": null
   }
  ],
  "shapes_recognised": [],
  "recover_with": [],
  "next": "describe_entity(entity_id=<a candidate's entity_id>, on=<date>)"
 },
 "unit": "ontology_entity",
 "vintage": "2026-10-28",
 "source": {
  "dataset": "Vlada ontology layer one (who holds and who owns every payer instrument, over time)",
  "publisher": "vlada",
  "catalog_updated_at": "2026-10-28"
 },
 "caveats": [],
 "response_hash": "8392da4fa816dd83869de7d70d18c4387d7ecd42181cdfd482400dd8e4f1e269",
 "semantic_version": 1,
 "tool_version": "resolve_entity@2.0.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "ontology_entity",
  "scope": {
   "tool": "resolve_entity",
   "filters": {
    "text": "Humana Inc.",
    "limit": 25
   }
  }
 },
 "method": "Computed over the filters shown in this answer's scope, from the sources listed in its evidence. Nothing outside those filters was included. You did not specify limit; 25 was used.",
 "evidence": {
  "sources": [
   {
    "dataset": "Vlada ontology layer one (who holds and who owns every payer instrument, over time)",
    "publisher": "vlada",
    "catalog_updated_at": "2026-10-28"
   }
  ],
  "response_hash": "8392da4fa816dd83869de7d70d18c4387d7ecd42181cdfd482400dd8e4f1e269"
 },
 "defaults_applied": [
  {
   "param": "limit",
   "used": 25,
   "reason": "tool default"
  }
 ]
}
```

REST: `POST https://api.vladahealth.com/v1/tools/resolve_entity` with the inputs as the JSON body. MCP: the tool by name.