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

# Service Code Groups (BETOS / RBCS / Service Group)

> List code groups across three taxonomies and pull every CPT/HCPCS code assigned to a group, with optional descendant rollup.

The platform classifies every HCPCS/CPT code along **three orthogonal taxonomies** so you can choose the grouping that fits the analysis you need:

| Taxonomy            | What it is                                                                                                                 | When to use it                                                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **`service_group`** | Coarse CPT-range groupings (E/M, Surgical, Radiology, …). One row per `ServiceGroup`.                                      | Documentation rules, modifier guidance, billing-form selection. This is what the `L5 service group` knowledge layer resolves to. |
| **`betos`**         | CMS BETOS-1 taxonomy (\~190 leaf categories under 8 top-level groups: M / P / I / T / D / O / Y / Z).                      | Utilization analytics that need to match CMS published BETOS reports (pre-2021).                                                 |
| **`rbcs`**          | CMS Restructured BETOS Classification System (2021+). 4-level hierarchy that supersedes BETOS-1 in newer CMS publications. | Modern utilization analytics, Medicare spending analyses, MIPS / QPP measure development.                                        |

A single CPT code carries **one assignment per taxonomy** at the same time — e.g. CPT `13100` is `service_group=surgical`, `betos_code=P5A`, `rbcs_code=PROC.SKIN.REPAIR`.

## List groups in a taxonomy

```bash theme={null}
# Default: legacy service_group buckets
curl "https://api-dev.rcintell.com/v1/codes/groups" \
  -H "X-API-Key: kp_test_..."

# BETOS-1 leaves (those that codes are actually assigned to)
curl "https://api-dev.rcintell.com/v1/codes/groups?taxonomy=betos&leaves_only=true" \
  -H "X-API-Key: kp_test_..."

# Full RBCS hierarchy (parents + leaves)
curl "https://api-dev.rcintell.com/v1/codes/groups?taxonomy=rbcs&leaves_only=false" \
  -H "X-API-Key: kp_test_..."
```

### Query parameters

| Param         | Type                                 | Default         | Meaning                                                                     |
| ------------- | ------------------------------------ | --------------- | --------------------------------------------------------------------------- |
| `taxonomy`    | `service_group` \| `betos` \| `rbcs` | `service_group` | Which taxonomy to list.                                                     |
| `leaves_only` | bool                                 | `true`          | For `betos`/`rbcs`: return only leaf nodes. Ignored for `service_group`.    |
| `year`        | int                                  | latest on file  | Taxonomy year. CMS revises BETOS/RBCS yearly.                               |
| `category`    | string                               | —               | Filter by taxonomy category (e.g. `imaging`). Only used for `betos`/`rbcs`. |

### Response (BETOS / RBCS)

```json theme={null}
[
  {
    "taxonomy": "betos",
    "code": "M1A",
    "name": "Office visits — new",
    "description": "New patient evaluation and management visits",
    "parent_code": "M",
    "level": 2,
    "category": "evaluation_and_management",
    "is_leaf": true,
    "code_count": 5
  },
  {
    "taxonomy": "betos",
    "code": "P5A",
    "name": "Skin and subcutaneous tissue",
    "description": "Repair, excision, and destruction of skin lesions",
    "parent_code": "P",
    "level": 2,
    "category": "procedures",
    "is_leaf": true,
    "code_count": 8
  }
]
```

`code_count` is the number of HCPCS/CPT codes in this platform's catalog currently assigned to that leaf — handy for sizing the impact of a coding change before drilling in.

### Response (service\_group)

```json theme={null}
[
  {
    "slug": "em",
    "name": "Evaluation & Management",
    "description": "Office visits, hospital visits, consultations",
    "cpt_range": "99202-99499",
    "billing_specialty": "primary_care",
    "requires_modifier": false,
    "key_modifiers": ["25", "57"],
    "documentation_requirements": "MDM or total time"
  }
]
```

## List codes assigned to a group

```bash theme={null}
# Every code in BETOS-1 leaf "M1A"
curl "https://api-dev.rcintell.com/v1/codes/groups/betos/M1A/codes" \
  -H "X-API-Key: kp_test_..."

# Every code under BETOS top-level "P" (Procedures), rolled up from descendants
curl "https://api-dev.rcintell.com/v1/codes/groups/betos/P/codes?include_descendants=true" \
  -H "X-API-Key: kp_test_..."

# Every code in an RBCS leaf
curl "https://api-dev.rcintell.com/v1/codes/groups/rbcs/PROC.SKIN.REPAIR/codes" \
  -H "X-API-Key: kp_test_..."

# Every code in a service_group slug
curl "https://api-dev.rcintell.com/v1/codes/groups/service_group/surgical/codes?limit=200" \
  -H "X-API-Key: kp_test_..."
```

### Query parameters

| Param                 | Type | Default | Meaning                                                                                                                                     |
| --------------------- | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `offset`              | int  | `0`     | Pagination offset.                                                                                                                          |
| `limit`               | int  | `100`   | Page size (max `500`).                                                                                                                      |
| `include_descendants` | bool | `true`  | When the group is a non-leaf category (e.g. BETOS `P`), include codes from all leaves under it. Ignored for leaf nodes and `service_group`. |

### Response

```json theme={null}
{
  "taxonomy": "betos",
  "group_code": "M1A",
  "group_name": "Office visits — new",
  "total": 5,
  "codes": [
    { "code": "99202", "code_type": "cpt", "short_description": "Office o/p new low 15-29 min", "category": "Evaluation and Management" },
    { "code": "99203", "code_type": "cpt", "short_description": "Office o/p new low 30-44 min", "category": "Evaluation and Management" }
  ]
}
```

## How assignments are loaded

BETOS / RBCS taxonomy nodes and CPT-to-group assignments live in `data/seed/betos_classifications.yaml` and are loaded by the `cms_betos_loader`. A refresh updates both the `betos_classifications` table and the denormalised `service_codes.betos_code` / `service_codes.rbcs_code` columns:

```bash theme={null}
curl -X POST "https://api-dev.rcintell.com/v1/admin/data/refresh" \
  -H "X-API-Key: kp_test_..."
```

The response includes `betos_nodes` (nodes upserted) and `betos_assignments` (CPT codes whose group changed).

<Note>
  The denormalised `*_code` columns make a single code → group lookup a one-column read. The hierarchy table is only consulted when you need parent/child rollup or category metadata.
</Note>