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

# Client Schema - Compact Table Test Layout

> Core client demographics and identifiers (compact 4-column table prototype)

> [!WARNING]
>
> **Development Note:** This is a prototype page testing a **compact 4-column table** layout for schema field references. It merges `BHA Column Name` + `Field Name` into a single **Field** column and combines `Valid Values` + `Notes` into a **Details** column (\~30-35% width savings). Compare against the [standard 6-column tables](https://coloradobehavioralhealthadministration.mintlify.site/schemas/client.md) and the [ResponseField card layout](https://coloradobehavioralhealthadministration.mintlify.site/schemas/client-test.md) to evaluate readability and mobile experience.

> [!NOTE]
>
> **Record Type:** `CLI` | **Version:** CoBHRM 2026-Q3 | **Parent:** None | **Children:** ADMISSION

## Overview

The CLIENT schema captures core demographic information for individuals receiving behavioral health services. This is the root record type - all other records reference a client through the `BHASO_CLIENT_IDENTIFIER`.

> [!NOTE]
>
> **Transaction Types:** All record types support Add (`A`), Update (`U`), and Replace (`R`) transactions. See [Transaction Types](https://coloradobehavioralhealthadministration.mintlify.site/getting-started/transaction-types.md) for details.

***

## 1. Schema Reference

<sub>**●** Required **◐** Conditional **○** Optional</sub>

### Identifier Fields

| Field | Fmt | Req | Details |
| - | - | - | - |
| Record Type  `RECORD_TYPE` | x(3) | ● | `CLI` — case-sensitive |
| Transaction Type  `TRANSACTION_TYPE` | x(1) | ● | `A`, `U`, `R` — See [Transaction Types](https://coloradobehavioralhealthadministration.mintlify.site/getting-started/transaction-types.md) |
| Client Identifier  `BHASO_CLIENT_IDENTIFIER` | x(-) | ● | Alphanumeric — Unique client ID from BHASO system |
| Effective Date  `EFFECTIVE_DATE` | date | ● | `YYYY-MM-DD` — Determines most recent record |
| Colorado PEAK State ID  `STATE_IDENTIFIER` | x(7) | ● | Pattern `X999999` — Also the Medicaid ID. Required |
| TRAILS ID  `TRAILS_IDENTIFIER` | 9(10) | ◐ | 10-digit number — Required if `CHILD_WELFARE_INVOLVEMENT = 1` |
| Verato Identifier  `VERATO_IDENTIFIER` | x(-) | ◐ | Alphanumeric — Can be blank for new clients; use existing Verato ID if supplied by BHA |
| BHA Identifier  `BHA_IDENTIFIER` | x(41) | ◐ | Pattern `BHRM-{UUID}` — Data conversion field for legacy records |

### Demographic Fields

| Field | Fmt | Req | Details |
| - | - | - | - |
| Date of Birth  `DOB` | date | ● | `YYYY-MM-DD` — Must be before record creation; age cannot exceed 120 years |
| Last Name  `LAST_NAME` | x(50) | ● | Text — Regex: `[\p{L} -']+` |
| First Name  `FIRST_NAME` | x(50) | ● | Text — Regex: `[\p{L} -']+` |
| Middle Name/Initial  `MIDDLE_NAME_INITIAL` | x(50) | ○ | Text — Regex: `[\p{L} -']?` |
| Name Suffix  `NAME_SUFFIX` | x(10) | ○ | Text — Regex: `[\p{L} -']+` |
| Social Security Number  `SSN` | x(12) | ○ | `999-99-9999` — Highly recommended. `000-00-0000` = No SSN, `777-77-7777` = Client Refused, `999-99-9999` = Unknown (WM only) |
| Sex at Birth  `SEX_AT_BIRTH` | 9(2) | ● | See [Sex at Birth](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/gender-codes/sex-at-birth.md) — Numeric code (e.g., `01`, `02`). Drives pregnancy/postpartum logic |
| Gender Identity  `GENDER_IDENTITY` | 9(2) | ○ | See [Gender Identity](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/gender-codes/gender-identity.md) — Optional if Sex at Birth is provided |
| Sexual Orientation  `SEXUAL_ORIENTATION` | 9(2) | ● | See [Sexual Orientation](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/gender-codes/sexual-orientation.md) |
| Race Codes  `RACE_CODES` | x(50) | ● | See [Race Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/race-ethnicity/race-codes.md) — Multi-value, semicolon+space (`; `) delimited |
| Ethnicity  `ETHNICITY` | 9(2) | ● | See [Ethnicity Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/race-ethnicity/ethnicity-codes.md) |
| Household Language  `HOUSEHOLD_LANGUAGE` | 9(2) | ○ | See [Household Language](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/demographics/household-language.md) — Triggers Communication Accommodations if not English |
| Disability Codes  `DISABILITY_CODES` | x(100) | ● | See [Disability Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/disabilities.md) — Multi-value, semicolon+space (`; `) delimited |
| Veteran Status  `VETERANS_STATUS` | bit | ● | `1` / `0` — Required for age 18+; use `0` for clients under 18 |
| Child Welfare Involvement  `CHILD_WELFARE_INVOLVEMENT` | bit | ○ | `1` / `0` — If `1`, `TRAILS_IDENTIFIER` is required |

### Location Fields

| Field | Fmt | Req | Details |
| - | - | - | - |
| County of Residence  `COUNTY_RESIDENCE` | 9(2) | ● | See [Counties](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/counties.md) — 2-digit code. Use county of location if houseless. `77` = Out of State, `99` = Unknown (WM only) |
| Zip Code of Residence  `ZIPCODE_RESIDENCE` | x(10) | ◐ | `99999` or `99999-9999` — Required unless County is `77` or `99` |
| Last Known Address Line 1  `LAST_KNOWN_ADDRESS_LINE_1` | x(100) | ○ | Text — Null for homeless/houseless and Out of State |
| Last Known Address Line 2  `LAST_KNOWN_ADDRESS_LINE_2` | x(100) | ○ | Text — Null for homeless/houseless and Out of State |
| Last Known City  `LAST_KNOWN_CITY` | x(100) | ○ | Text — Null for homeless/houseless and Out of State |
| RAE Region  `RAE_REGION` | 9(1) | ◐ | `1`-`4` — Required if any part of admission treatment is Medicaid-funded |

### System Metadata Fields

These fields are required in every submission and track record creation and modification:

| BHA Column Name | Field Name | Format | Required | Notes |
| - | - | - | - | - |
| `CREATED_DATE` | Created Date | `yyyy-mm-dd HH24:MI:SS.FF` | Y | Date/time record was created |
| `CREATED_BY` | Created By | `x(100)` | Y | User/system that created the record |
| `LAST_UPDATED_DATE` | Last Updated Date | `yyyy-mm-dd HH24:MI:SS.FF` | Y | If `TRANSACTION_TYPE = A`, must equal `CREATED_DATE` |

***

## 2. Examples

### Minimal Valid Example

Only required fields populated. This is an adult male client in Denver with no disabilities.

```csv theme={null}
RECORD_TYPE|TRANSACTION_TYPE|BHASO_CLIENT_IDENTIFIER|EFFECTIVE_DATE|DOB|LAST_NAME|FIRST_NAME|SEX_AT_BIRTH|SEXUAL_ORIENTATION|RACE_CODES|ETHNICITY|COUNTY_RESIDENCE|ZIPCODE_RESIDENCE|DISABILITY_CODES|VETERANS_STATUS|CREATED_DATE|CREATED_BY|LAST_UPDATED_DATE
CLI|A|CLT-000001|2024-01-15|1990-05-15|Smith|John|02|01|05|01|17|80202|01|0|2024-01-15 10:00:00|system|2024-01-15 10:00:00
```

### Complete Example

All fields populated. Female client with Medicaid, multiple races, child welfare involvement, and full address.

```csv theme={null}
RECORD_TYPE|TRANSACTION_TYPE|BHASO_CLIENT_IDENTIFIER|EFFECTIVE_DATE|STATE_IDENTIFIER|TRAILS_IDENTIFIER|VERATO_IDENTIFIER|BHA_IDENTIFIER|DOB|LAST_NAME|FIRST_NAME|MIDDLE_NAME_INITIAL|NAME_SUFFIX|SSN|SEX_AT_BIRTH|GENDER_IDENTITY|SEXUAL_ORIENTATION|RACE_CODES|ETHNICITY|HOUSEHOLD_LANGUAGE|COUNTY_RESIDENCE|ZIPCODE_RESIDENCE|LAST_KNOWN_ADDRESS_LINE_1|LAST_KNOWN_ADDRESS_LINE_2|LAST_KNOWN_CITY|RAE_REGION|DISABILITY_CODES|VETERANS_STATUS|CHILD_WELFARE_INVOLVEMENT|CREATED_DATE|CREATED_BY|LAST_UPDATED_DATE
CLI|A|CLT-000002|2024-02-10|A123456|1234567890|VRT-00123|BHRM-00000000-0000-0000-0000-000000000000|1996-08-22|Garcia|Maria|L||123-45-6789|01|03|01|03; 05|05|02|21|80903|456 Pine Ave|Unit 12|Colorado Springs|4|02; 15|0|1|2024-02-10 09:30:00|jdoe|2024-02-10 09:30:00
```

### Edge Cases

Multi-value race fields (semicolon-space delimited), international characters in name, and an out-of-state client.

```csv theme={null}
RECORD_TYPE|TRANSACTION_TYPE|BHASO_CLIENT_IDENTIFIER|EFFECTIVE_DATE|DOB|LAST_NAME|FIRST_NAME|MIDDLE_NAME_INITIAL|SSN|SEX_AT_BIRTH|SEXUAL_ORIENTATION|RACE_CODES|ETHNICITY|COUNTY_RESIDENCE|DISABILITY_CODES|VETERANS_STATUS|CREATED_DATE|CREATED_BY|LAST_UPDATED_DATE
CLI|A|CLT-000003|2024-03-01|1985-11-30|O'Brien-Müller|François|J|000-00-0000|02|98|01; 04|01|77|01|1|2024-03-01 08:00:00|system|2024-03-01 08:00:00
```

> [!NOTE]
>
> The client above is out-of-state (`COUNTY_RESIDENCE = 77`), so `ZIPCODE_RESIDENCE` is not required. The SSN `000-00-0000` indicates "No SSN." International characters like `ü` and `ç` are supported via UTF-8 encoding.

> [!NOTE]
>
> **Recommendation** — This section contains guidance developed by the documentation team to supplement the CoBHRM specification. Reviewers should evaluate whether to adopt, modify, or remove this content.

### Invalid Example with Errors

```csv theme={null}
RECORD_TYPE|TRANSACTION_TYPE|BHASO_CLIENT_IDENTIFIER|EFFECTIVE_DATE|DOB|LAST_NAME|FIRST_NAME|SEX_AT_BIRTH|SEXUAL_ORIENTATION|RACE_CODES|ETHNICITY|COUNTY_RESIDENCE|ZIPCODE_RESIDENCE|DISABILITY_CODES|VETERANS_STATUS|CHILD_WELFARE_INVOLVEMENT|CREATED_DATE|CREATED_BY|LAST_UPDATED_DATE
CLI|A||2024-01-15|1900-01-01||Jane|01|01|05|01|17|80202|01|0|1|2024-01-15 10:00:00|system|2024-01-15 10:00:00
```

***

## 3. Template

> **[View CLIENT Template](https://coloradobehavioralhealthadministration.mintlify.site/reference/templates/downloads.md#client-template-cli)**
>
> CLIENT schema template with headers and sample row

***

## 4. Parsing Rules

### CSV Parsing Rules

| Property | Value |
| - | - |
| Encoding | UTF-8 |
| Delimiter | Pipe (`\|`) |
| Quote Character | Double quote (`"`) |
| Escape | Backslash (`\`) |
| Date Format | `YYYY-MM-DD` |
| Timestamp Format | `YYYY-MM-DD HH24:MI:SS.FF` (Mountain Time) |
| Null Representation | Empty field (`\|\|`) |

See [File Format Requirements](https://coloradobehavioralhealthadministration.mintlify.site/getting-started/file-format-requirements.md) for full details on encoding, quoting, data types, and null handling.

> [!NOTE]
>
> **Multi-value delimiter:** `RACE_CODES` and `DISABILITY_CODES` use semicolon + space (`; `) to separate multiple values within a single field.

***

## 5. Update Semantics

### Primary Key

`BHASO_CLIENT_IDENTIFIER` + `EFFECTIVE_DATE`

### Transaction Types

| Type | Code | Behavior |
| - | - | - |
| Add | `A` | Creates new client record; fails if client+effective\_date exists |
| Update | `U` | Creates new effective-dated version of existing client |
| Replace | `R` | Overwrites most recent client record (error corrections) |

### Idempotency

* Most recent record determined by `EFFECTIVE_DATE`
* System uses SCD Type 2 - all historical records retained
* Query for "current" client returns record with latest `EFFECTIVE_DATE`

***

## Related Schemas

| Schema | Relationship | Key Field |
| - | - | - |
| [ADMISSION](https://coloradobehavioralhealthadministration.mintlify.site/schemas/admission.md) | Child | `BHASO_CLIENT_IDENTIFIER` |
| [DISCHARGE](https://coloradobehavioralhealthadministration.mintlify.site/schemas/discharge.md) | Grandchild | `BHASO_CLIENT_IDENTIFIER` |


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