PAYORMAP DEVELOPER PLATFORM · BETA

Dental reimbursement and entity intelligence, as an API.

Use the same governed concepts that power PayorMap—entity relationships, observed rates, benchmarks, opportunities, payer coverage, Medicaid and contracts—inside diligence, BI, contracting and AI workflows.

Base URLhttps://payormap.com/api/v1

Version 1 is read-only. The API exposes PayorMap concepts rather than raw database tables, and company-specific resources are restricted to companies assigned to the API key's organization.

Authentication

Send the organization API key in either header format:

x-api-key: pm_live_...

Authorization: Bearer pm_live_...

Keys are stored only as SHA-256 hashes. The plaintext key is shown once when created.

API keys

Organization owners and admins can create and revoke read-only keys below while signed into PayorMap with MFA. New keys include the read:entities scope by default.

Endpoints

GET /companiesAccessible companies

Organization-scoped company list.

GET /entitiesEntity Intelligence

TIN → legal entity → brand → platform → parent → sponsor.

GET /entities/{tin}TIN resolution

One governed entity record with evidence and finance-grade eligibility.

GET /ratesObserved reimbursement

Company/payer/CDT summaries from clean finance-grade TINs only.

GET /benchmarksBenchmarks

P10/P25/P50/P75/P90 with sample and vintage evidence.

GET /opportunitiesModeled opportunity

Below-market gaps from clean finance-grade TINs only.

GET /payersPayer coverage

Source, normalization and production-readiness status.

GET /medicaidMedicaid rates

Published state dental fee schedule evidence.

GET /contractsContracts

Organization-private contract metadata.

GET /contracts/{id}/market-comparisonContract vs market

Fee schedule rows matched to payer benchmarks.

GET /methodologyMethodology

Field definitions and interpretation rules.

Entity example

curl -H "x-api-key: $PAYORMAP_API_KEY" \
  "https://payormap.com/api/v1/entities/823275172"

Opportunity example

curl -H "x-api-key: $PAYORMAP_API_KEY" \
  "https://payormap.com/api/v1/opportunities?company=Ideal%20Dental&payer=UnitedHealthcare&state=TX&code=D2740"

Entity Intelligence

PayorMap separates entity identity from TIN/provider-cluster quality. A TIN can be correctly identified as a practice brand or support-platform affiliate while still containing provider rows that are too mixed to use in reimbursement economics.

Field	Meaning
`legal_entity_name`	Best-supported legal or organization name associated with the TIN.
`brand_name`	Market-facing practice or brand identity.
`platform_company`	Governed DSO/OSO/support platform attribution.
`parent_company`	Parent/support organization when distinct from the market brand.
`pe_firm`	Mapped financial sponsor when available.
`identity_status`	Verified/high/review/rejected identity conclusion.
`cluster_status`	Clean, conflict or unresolved TIN→NPI/provider cluster.
`production_eligible`	True only when a verified/high identity also has a clean cluster and can enter finance-grade rate/opportunity calculations.

Response semantics

The API intentionally keeps observed evidence, benchmark evidence, entity evidence and modeled value separate.

Field	Meaning
`median_rate`	Observed median reimbursement for the scoped company/payer/CDT evidence.
`market_p50`	Median market benchmark for the relevant cohort.
`market_p75`	Upper-quartile scenario, not an automatic achievable target.
`source_rate_count`	Rate observations supporting the opportunity row.
`source_distinct_npis`	Distinct NPIs represented in the evidence.
`estimated_annual_units_base`	Modeled utilization unless replaced by validated client T12 units.
`gross_opportunity_to_p50_base`	Directional annual value using the model's base utilization assumptions.
`modeled_opportunity_confidence_level`	Confidence signal for the modeled opportunity.

Underwriting ruleDo not treat modeled opportunity as committed value until company/entity mapping, TIN cluster, governing contract/network, source vintage and actual T12 utilization are validated.

MCP

The read-only MCP adapter uses the same authentication, organization scope and semantic layer as the API.

Endpointhttps://payormap.com/api/mcp

Available tools include get_entity_intelligence, get_companies, search_rates, get_benchmarks, get_opportunities, get_payer_coverage, get_medicaid_rates, get_contracts, get_contract_vs_market, and get_methodology.

MCP is a thin adapter over the v1 semantic layer; it does not query raw Supabase tables independently.

Limits & beta notes

v1 is read-only.
Most list endpoints default to 100 rows and enforce endpoint-specific maximums.
Company-specific calls are restricted by the organization-to-company access map.
Rates and opportunities are now gated to clean finance-grade TIN mappings.
Entity Intelligence keeps market brand, support platform and parent organization separate.
Contracts are restricted by organization_id.
Payer coverage status distinguishes source availability from normalization and production readiness.

For the full methodology, payer coverage library and current limitations, use the PayorMap Resource Center.