2.5 Organization structure, facilities, and billing entities

Outcome

The tenant has its full organization tree configured: organization → facilities → sites, plus the billing entities (with NPIs) that will appear on outbound 837 claims.

Prerequisites

• 2.4 First tenant admin complete.

Concept map

Steps

1. Create the organization

   Impersonate the tenant → Admin → Organizations → Add organization.

   Field	Value
   Legal name	Acme Behavioral Health, LLC
   Tax ID (EIN)	12-3456789
   Default address	…

2. Create facilities

   Admin → Facilities → Add facility. For each:

   Field	Value
   Name	Acme Cleveland Clinic
   NPI	1234567890 (checksum-validated)
   Taxonomy	261QM0801X (Behavioral Health Counseling)
   Address	…
   State	OH
   Time zone	America/New_York

   The NPI input enforces the Luhn-derived NPI checksum. A mistyped NPI is rejected client-side.

3. Create sites within each facility

   A site is a sub-location at a facility — used when a customer needs to bill differently per program (e.g. residential vs. outpatient under the same NPI). Optional for many customers; required for the IOP example above.

4. Create billing entities

   Admin → Billing entities → Add billing entity. The billing entity is the legal submitter on the 837. Most customers have one billing entity per legal entity.

   Field	Value
   Name	Acme Behavioral Health, LLC
   Group / billing NPI	1234567892
   Tax ID	12-3456789
   Entity type	GROUP (or INDIVIDUAL for solo practices)

5. Link billing entity to facilities

   In Admin → Billing entities → <entity> → Facilities, select all the facilities the entity bills for. Most customers have a single billing entity covering all facilities; multi-entity customers map carefully.

Validation

Check	Expected
identity.organization count	1
identity.facility count	matches step 2 input
All NPIs have correct checksum	UI rejects invalid; check via npi_validate(facility.npi) SQL helper
billing.billing_entity count	matches step 4
billing.billing_entity_facility link table	rows present for every facility billed

Troubleshooting

Symptom	Likely cause	Fix
NPI rejected	Bad checksum	Confirm the NPI on NPPES (https://npiregistry.cms.hhs.gov).
Conflict on facility name	Duplicate within tenant	Append suffix (e.g. — Cleveland) and retry.
Cannot link facility to billing entity	Different state and you have a state-locked billing entity	Most contracts allow same-state linkage only — confirm with the customer's billing lead.

Next

2.6 — Payers and program configs