> ## 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.

# CLI - Client

> Core client demographics and identifiers

> [!WARNING]
>
> **Development Note:** We are testing alternative layouts for schema field references. Compare this page against the [API-style card layout](https://coloradobehavioralhealthadministration.mintlify.site/schemas/client-test.md) and the [compact 4-column table layout](https://coloradobehavioralhealthadministration.mintlify.site/schemas/client-test-compact.md) in the Experimental Schema Layouts section, then share your feedback.

> [!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

### Identifier Fields

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

### Data Fields

| BHA Column Name | Field Name | Format | Required | Valid Values | Notes |
| - | - | - | - | - | - |
| `DOB` | Date of Birth | `date` | Y | `YYYY-MM-DD` | Age must be 0-120 years when compared against each Admission Date associated with the client |
| `LAST_NAME` | Last Name | `x(50)` | Y | Text | Regex: `[\p{L} -']+` |
| `FIRST_NAME` | First Name | `x(50)` | Y | Text | Regex: `[\p{L} -']+` |
| `MIDDLE_NAME_INITIAL` | Middle Name/Initial | `x(50)` | N | Text | Regex: `[\p{L} -']?` |
| `NAME_SUFFIX` | Name Suffix | `x(10)` | N | Text | Regex: `[\p{L} -']+` |
| `SSN` | Social Security Number | `x(12)` | N | `999-99-9999` | Highly recommended. Special values: `000-00-0000` = No SSN, `777-77-7777` = Client Refused, `999-99-9999` = Unknown (Withdrawal Management only) |
| `COUNTY_RESIDENCE` | County of Residence | `9(2)` | Y | 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) |
| `ZIPCODE_RESIDENCE` | Zip Code of Residence | `x(10)` | Conditional | `99999` or `99999-9999` | Required unless County is `77` (Out of State) or `99` (Unknown) |
| `RACE_CODES` | Race Codes | `x(50)` | Y | See [Race Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/race-ethnicity/race-codes.md) | Multi-value, semicolon+space (`;` ) delimited |
| `ETHNICITY` | Ethnicity | `9(2)` | Y | See [Ethnicity Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/race-ethnicity/ethnicity-codes.md) | |
| `HOUSEHOLD_LANGUAGE` | Household Language | `9(2)` | N | See [Household Language](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/demographics/household-language.md) | Triggers Communication Accommodations if not English |
| `SEX_AT_BIRTH` | Sex at Birth | `9(2)` | Y | 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)` | N | See [Gender Identity](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/gender-codes/gender-identity.md) | Optional if Sex at Birth is M/F |
| `SEXUAL_ORIENTATION` | Sexual Orientation | `9(2)` | Y | See [Sexual Orientation](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/gender-codes/sexual-orientation.md) | |
| `CHILD_WELFARE_INVOLVEMENT` | Child Welfare Involvement | `bit` | N | `1` / `0` | If `1`, `TRAILS_IDENTIFIER` is required |
| `DISABILITY_CODES` | Disability Codes | `x(100)` | Y | See [Disability Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/disabilities.md) | Multi-value, semicolon+space (`;` ) delimited |
| `VETERANS_STATUS` | Veteran Status | `bit` | Y | `1` / `0` | Required for age 18 or older; use `0` for clients under 18 |
| `LAST_KNOWN_ADDRESS_LINE_1` | Last Known Address Line 1 | `x(100)` | N | Text | Null for homeless/houseless and Out of State. Validated alongside `LAST_KNOWN_ADDRESS_LINE_2` and `LAST_KNOWN_CITY` |
| `LAST_KNOWN_ADDRESS_LINE_2` | Last Known Address Line 2 | `x(100)` | N | Text | Null for homeless/houseless and Out of State. Validated alongside `LAST_KNOWN_ADDRESS_LINE_1` and `LAST_KNOWN_CITY` |
| `LAST_KNOWN_CITY` | Last Known City | `x(100)` | N | Text | Null for homeless/houseless and Out of State |
| `RAE_REGION` | RAE Region | `9(1)` | Conditional | `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|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-000001|2024-01-15|B234567||||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

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

```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|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-000003|2024-03-01|C345678||||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.

***

## 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

`RECORD_TYPE` + `BHASO_CLIENT_IDENTIFIER`

### Transaction Types

| Type | Code | Behavior |
| - | - | - |
| Add | `A` | Creates new client record; fails if a record with the same `BHASO_CLIENT_IDENTIFIER` already 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` |


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