> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pricemedic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payers, Payer Groups, Lines of Business and Practices

> How PriceMedic defines its core contracting entities and how their IDs relate

## Overview

Four registry entities describe who is contracting and for which population.

| Entity | Definition | Scope |
| - | - | - |
| [Payer](#payer) | The entity that adjudicates and pays the claim | Global list plus your organization's own payers |
| [Payer Group](#payer-group) | The parent organization a payer rolls up to | Your organization |
| [Line of Business](#line-of-business) | The population or product line covered | Your organization |
| [Practice](#practice) | The billing entity that holds the contract | Your organization |

The entities don't reference each other directly. They are linked through [canonical observations](#how-the-ids-relate).

## Payer

Payers come from two tiers:

* **Global payers** are shared by every organization. The list is built from the Stedi payer network, NAIC-registered insurers, government programs and self-pay.
* **Organization payers** exist only for your organization, such as a local TPA. If one has the same name as a global payer, yours takes precedence.

| Column | Type | Description |
| - | - | - |
| `id` | uuid | Internal payer ID |
| `id_int64` | bigint | Stable integer ID, unique across all payers |
| `name` | string | Canonical payer name |
| `is_global` | boolean | `true` for global payers |
| `role` | string | Optional role of the payer in a contract |

Global payers also carry matching attributes:

| Column | Description |
| - | - |
| `payer_type` | How the payer is keyed: `stedi`, `naic`, `ein`, `government` or `self_pay` |
| `stedi_id` | Stedi's permanent payer ID |
| `primary_payer_id` | Main EDI payer ID used on claims. Can change over time |
| `aliases` | Every EDI payer ID that routes to this payer |
| `dba` | Trade names, acronyms and former names |
| `naic_code`, `ein`, `eins` | Regulatory identifiers |
| `parent_payer_group_name` | Parent organization reported by the source network. Informational only |
| `programs` | Supported programs, e.g. `COMMERCIAL`, `MEDICARE`, `MEDICAID` |
| `coverage_types` | `medical`, `dental`, `vision` |
| `operating_states` | States the payer operates in |
| `active` | `false` once the payer leaves the source network. The row is kept |

### id\_int64 ranges

| Range | Assigned to |
| - | - |
| 1,000 to 999,999 | Global payers whose ID was adopted from a customer's existing integer ID |
| 1,000,000 and up | All other payers, global and organization, assigned in sequence |

A small number of adopted IDs also sit at 9,000,000 and up. IDs are unique and never reused, but don't rely on the range to tell global and organization payers apart; use `is_global`.

## Payer Group

| Column | Type | Description |
| - | - | - |
| `id` | uuid | Internal payer group ID |
| `name` | string | Group name, unique within your organization |

Groups are seeded from the parent payers of the payers you contract with. A payer has no fixed group column. The payer-to-group link is recorded on each observation, so the same payer can roll up differently in different contexts.

## Line of Business

| Column | Type | Description |
| - | - | - |
| `id` | uuid | Internal LOB ID |
| `name` | string | LOB name |
| `bucket` | string | Optional roll-up category: `Commercial`, `Government` or `Other`. Can be empty |

Organizations seeded with PriceMedic's standard list get these values. Organizations whose lines of business come from their own data, for example during mastering, have their own list, and `bucket` may be empty:

| Line of Business | Bucket |
| - | - |
| Commercial | Commercial |
| Marketplace | Commercial |
| Medicare | Government |
| Medicare Advantage | Government |
| Medicaid | Government |
| Government | Government |
| Workers' Compensation | Other |
| Self-Pay | Other |
| Vision | Other |
| Secondary | Other |
| Other | Other |

Plan type alone doesn't set the LOB. A Medicare HMO is Medicare Advantage, not Medicare.

## Practice

| Column | Type | Description |
| - | - | - |
| `id` | uuid | Internal practice ID |
| `name` | string | Practice name |
| `ein` | string | Tax ID (TIN) |
| `group_npi` | string | Organizational (Type 2) NPI |
| `market` | string | Market or region |
| `type` | string | Practice type |

`name`, `ein` and `group_npi` are each unique within your organization. Incoming data that would give two practices the same TIN or NPI is flagged for review, not merged.

## How the IDs relate

Each record from your source data is resolved into a **canonical observation**: one row holding the IDs of the entities that appeared together. This is the only place the entities are linked.

| Column | Points to | Required |
| - | - | - |
| `practice_id` | Practice `id` | Yes |
| `payer_id` | Payer `id` | Yes |
| `lob_id` | Line of Business `id` | Yes |
| `payer_group_id` | Payer Group `id` | No |
| `network_id` | Network `id` | No |
| `counterparty_id` | Counterparty `id` | No |
| `bound_fields` | Names of the dimensions that are set | |
| `specificity` | Count of dimensions set. Higher is more specific | |

For example, one observation can say that Practice A contracts with Aetna, under the Aetna (CVS Group) payer group, for Medicare Advantage.

Raw values are matched to entities in this order: a payer already seen for the same practice, exact name, a prior resolution, fuzzy match, AI-assisted match, then human review. Each match records the method used.

## Data products

The entities are also published as tables in your organization's `registry` database:

| Table | Columns |
| - | - |
| `dim_payer_dp` | `id`, `id_int64`, `name`, `role`, `is_global`, `created_at`, `updated_at`, `org_slug`, `synced_at` |
| `dim_payer_group_dp` | `id`, `name`, `created_at`, `updated_at`, `org_slug`, `synced_at` |
| `dim_line_of_business_dp` | `id`, `name`, `bucket`, `created_at`, `updated_at`, `org_slug`, `synced_at` |
| `dim_practice_dp` | `id`, `name`, `ein`, `group_npi`, `market`, `type`, `created_at`, `updated_at`, `org_slug`, `synced_at` |
| `fact_canonical_observation_dp` | `id`, `practice_id`, `payer_group_id`, `payer_id`, `network_id`, `lob_id`, `counterparty_id`, `bound_fields`, `specificity`, `created_at`, `org_slug`, `synced_at` |

The `*_id` columns in `fact_canonical_observation_dp` join to `id` in the matching `dim_*_dp` table. `dim_payer_dp` includes your payers and all global payers, so every `payer_id` joins. `org_slug` identifies your organization and `synced_at` is the last refresh time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.