Lookup Rates For Tin
lookup_rates_for_tinLook 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tin | Yes | ||
| code | No | ||
| limit | No | 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. | |
| payer | Yes | ||
| state | Yes | ||
| offset | No | Rows to skip before this page. Pass the `paging.next_offset` from the previous answer. | |
| version | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tin | No | ||
| code | No | ||
| unit | No | ||
| as_of | No | ||
| limit | No | ||
| payer | No | ||
| state | No | ||
| value | No | ||
| offset | No | ||
| paging | No | ||
| source | No | ||
| status | No | complete | |
| caveats | No | ||
| failure | No | ||
| quality | No | ||
| refusal | No | ||
| version | No | ||
| vintage | No | ||
| headline | No | ||
| no_match | No | ||
| tin_found | No | ||
| rate_count | No | ||
| explanation | No | ||
| methodology | No | ||
| tool_version | No | unknown | |
| response_hash | No | ||
| matching_rates | No | ||
| bridge_pg_count | No | ||
| elapsed_seconds | No | ||
| freshness_state | No | unknown | |
| provider_groups | No | ||
| tin_index_paths | No | ||
| not_found_reason | No | ||
| semantic_version | No | ||
| invariants_applied | No | ||
| tin_business_names | No | ||
| membership_pg_count | No | ||
| returned_rate_count | No | ||
| provider_group_count | No | ||
| provider_specific_count | No | ||
| broad_applicability_count | No | ||
| returned_provider_group_count | No |