lookup_rates_for_tin

Lookup Rates For Tin

What it answers

Look up the negotiated rates a payer attaches to a tax entity (TIN/EIN), resolved at query time through the canonical graph: TIN → provider groups (idx_tin_provider_group) → pg_sets → rates. Accepts hyphenated EINs (normalized digits-only 9). Every result carries provenance: tin_business_name (the payer-asserted entity name), tin_scope_class (fanout class), and tin_index_path ('membership' = payer-asserted NPI↔TIN rows; 'bridge' = system-level group evidence). A TIN is system-shared, NOT building-exact — use lookup_rates_for_npi first for building-specific evidence; this is the fallback rung of the facility identity ladder. Payers without a TIN index (e.g. carefirst-class, no usable EIN rows) return an honest empty. PAGED: `limit` (default 25, max 500) and `offset` bound both `matching_rates` and `provider_groups`; `rate_count` / `provider_group_count` are the full totals and `paging` names what was cut plus the call that returns the next page. `value` is a COUNT, never a price: it is the TOTAL number of matching rates, `unit` says so, and `headline` spells it out in fields (kind=count, is_a_price=false). The prices themselves are one per row in `matching_rates`.

Inputs

payer

string · required

state

string · required

tin

string · required

code

any · optional

default: null

limit

integer · optional

Rows per page for `matching_rates` and `provider_groups` (default 25, max 500). The totals are always reported in full; `paging` says what was cut and how to ask for the next page.

default: 25

offset

integer · optional

Rows to skip before this page. Pass the `paging.next_offset` from the previous answer.

default: 0

version

any · optional

default: null

Call it

From an agent: connect the Vlada MCP once (one click for Claude, ChatGPT, Cursor, VS Code) and ask in plain English; the agent selects lookup_rates_for_tin when the question fits. From code: the same tool over REST with an API key. The schema endpoint needs no key.

curl -X POST https://api.vladahealth.com/v1/tools/lookup_rates_for_tin \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer":"<payer>","state":"<state>","tin":"<tin>"}'

curl https://api.vladahealth.com/v1/tools/lookup_rates_for_tin/schema      # the JSON schema, no auth
# MCP endpoint (Streamable HTTP): https://mcp.vladahealth.com/mcp

What comes back

Typed rows plus provenance on every answer: the public source file, its vintage, the methodology, and a response_hash you can replay. Prove and replay tools turn any number into a re-runnable receipt. A number the data cannot support comes back as “not in the data”, never as zero.

Output schema

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "properties": {
  "value": {
   "default": null,
   "title": "Value"
  },
  "unit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Unit"
  },
  "vintage": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Vintage"
  },
  "source": {
   "$ref": "#/$defs/Source"
  },
  "methodology": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Methodology"
  },
  "quality": {
   "$ref": "#/$defs/Quality"
  },
  "invariants_applied": {
   "items": {
    "type": "string"
   },
   "title": "Invariants Applied",
   "type": "array"
  },
  "caveats": {
   "items": {
    "type": "string"
   },
   "title": "Caveats",
   "type": "array"
  },
  "response_hash": {
   "default": "",
   "title": "Response Hash",
   "type": "string"
  },
  "semantic_version": {
   "default": 1,
   "title": "Semantic Version",
   "type": "integer"
  },
  "tool_version": {
   "default": "unknown",
   "title": "Tool Version",
   "type": "string"
  },
  "explanation": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Explanation"
  },
  "status": {
   "default": "complete",
   "title": "Status",
   "type": "string"
  },
  "refusal": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Refusal"
  },
  "failure": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Failure"
  },
  "as_of": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "As Of"
  },
  "freshness_state": {
   "default": "unknown",
   "title": "Freshness State",
   "type": "string"
  },
  "payer": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Payer"
  },
  "tin": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Tin"
  },
  "state": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "State"
  },
  "code": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Code"
  },
  "version": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Version"
  },
  "tin_found": {
   "default": false,
   "title": "Tin Found",
   "type": "boolean"
  },
  "headline": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Headline"
  },
  "provider_groups": {
   "items": {},
   "title": "Provider Groups",
   "type": "array"
  },
  "matching_rates": {
   "items": {},
   "title": "Matching Rates",
   "type": "array"
  },
  "rate_count": {
   "default": 0,
   "title": "Rate Count",
   "type": "integer"
  },
  "returned_rate_count": {
   "default": 0,
   "title": "Returned Rate Count",
   "type": "integer"
  },
  "provider_group_count": {
   "default": 0,
   "title": "Provider Group Count",
   "type": "integer"
  },
  "returned_provider_group_count": {
   "default": 0,
   "title": "Returned Provider Group Count",
   "type": "integer"
  },
  "limit": {
   "default": 25,
   "title": "Limit",
   "type": "integer"
  },
  "offset": {
   "default": 0,
   "title": "Offset",
   "type": "integer"
  },
  "paging": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Paging"
  },
  "tin_business_names": {
   "items": {},
   "title": "Tin Business Names",
   "type": "array"
  },
  "tin_index_paths": {
   "items": {},
   "title": "Tin Index Paths",
   "type": "array"
  },
  "membership_pg_count": {
   "default": 0,
   "title": "Membership Pg Count",
   "type": "integer"
  },
  "bridge_pg_count": {
   "default": 0,
   "title": "Bridge Pg Count",
   "type": "integer"
  },
  "provider_specific_count": {
   "default": 0,
   "title": "Provider Specific Count",
   "type": "integer"
  },
  "broad_applicability_count": {
   "default": 0,
   "title": "Broad Applicability Count",
   "type": "integer"
  },
  "elapsed_seconds": {
   "default": 0,
   "title": "Elapsed Seconds",
   "type": "number"
  }
 },
 "title": "TinRatesResponse",
 "type": "object"
}

Sources behind it

vlada_curated.fact_rate
vlada_curated.idx_rate_lookup

tables: vlada_curated.fact_rate · vlada_curated.idx_tin_provider_group · vlada_curated.idx_rate_lookup

Known limits

TIN evidence is system-shared, not building-exact
carefirst-class payers (NPI stuffed into tin_value) have no TIN index

As of the 2026-09-19 build of the served surface · machine-readable catalog · the live server may run a different version; the schema endpoint above is authoritative for what is deployed.