> ## 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 - API Style Test Layout
> Core client demographics and identifiers (ResponseField layout prototype)
> [!WARNING]
>
> **Development Note:** This is a prototype page testing an alternative layout for schema field references. It uses Mintlify's `ResponseField` component (card/list style) instead of the 6-column markdown tables used on the [standard CLIENT page](https://coloradobehavioralhealthadministration.mintlify.site/schemas/client.md). The goal is to compare readability, width, and mobile experience before deciding whether to adopt this layout across all schema pages.
> [!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
**RECORD\_TYPE** `x(3)` *required*
**Record Type** — Must be `CLI`, exact and case-sensitive.
**TRANSACTION\_TYPE** `x(1)` *required*
**Transaction Type** — `A` (Add), `U` (Update), or `R` (Replace). See [Transaction Types](https://coloradobehavioralhealthadministration.mintlify.site/getting-started/transaction-types.md).
**BHASO\_CLIENT\_IDENTIFIER** `x(-)` *required*
**Client Identifier** — Alphanumeric. Unique client ID from the BHASO system.
**EFFECTIVE\_DATE** `date` *required*
**Effective Date** — Format `YYYY-MM-DD`. Determines most recent record.
**STATE\_IDENTIFIER** `x(7)`
**Colorado PEAK State ID** — Pattern `X999999`. Also the Medicaid ID. Required.
**TRAILS\_IDENTIFIER** `9(10)`
**TRAILS ID** — 10-digit number. Required if `CHILD_WELFARE_INVOLVEMENT = 1`.
Conditional
**VERATO\_IDENTIFIER** `x(-)`
**Verato Identifier** — Alphanumeric. Can be blank for new clients; use existing Verato ID if supplied by BHA.
Conditional
**BHA\_IDENTIFIER** `x(41)`
**BHA Identifier** — Pattern `BHRM-{UUID}`. Data conversion field for legacy records.
### Demographic Fields
**DOB** `date` *required*
**Date of Birth** — Format `YYYY-MM-DD`. Must be before record creation; age cannot exceed 120 years.
**LAST\_NAME** `x(50)` *required*
**Last Name** — Text. Regex: `[\p{L} -']+`
**FIRST\_NAME** `x(50)` *required*
**First Name** — Text. Regex: `[\p{L} -']+`
**MIDDLE\_NAME\_INITIAL** `x(50)`
**Middle Name/Initial** — Text. Regex: `[\p{L} -']?`
**NAME\_SUFFIX** `x(10)`
**Name Suffix** — Text. Regex: `[\p{L} -']+`
**SSN** `x(12)`
**Social Security Number** — Format `999-99-9999`. Highly recommended. Special values: `000-00-0000` = No SSN, `777-77-7777` = Client Refused, `999-99-9999` = Unknown (Withdrawal Management only).
**SEX\_AT\_BIRTH** `9(2)` *required*
**Sex at Birth** — Numeric code (e.g., `01`, `02`). See [Sex at Birth](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/gender-codes/sex-at-birth.md). Drives pregnancy/postpartum logic.
**GENDER\_IDENTITY** `9(2)`
**Gender Identity** — See [Gender Identity](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/gender-codes/gender-identity.md). Optional if Sex at Birth is provided.
**SEXUAL\_ORIENTATION** `9(2)` *required*
**Sexual Orientation** — See [Sexual Orientation](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/gender-codes/sexual-orientation.md).
**RACE\_CODES** `x(50)` *required*
**Race Codes** — See [Race Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/race-ethnicity/race-codes.md). Multi-value, semicolon+space (`; `) delimited.
**ETHNICITY** `9(2)` *required*
**Ethnicity** — See [Ethnicity Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/race-ethnicity/ethnicity-codes.md).
**HOUSEHOLD\_LANGUAGE** `9(2)`
**Household Language** — See [Household Language](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/demographics/household-language.md). Triggers Communication Accommodations if not English.
**DISABILITY\_CODES** `x(100)` *required*
**Disability Codes** — See [Disability Codes](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/disabilities.md). Multi-value, semicolon+space (`; `) delimited.
**VETERANS\_STATUS** `bit` *required*
**Veteran Status** — `1` / `0`. Required for age 18 or older; use `0` for clients under 18.
**CHILD\_WELFARE\_INVOLVEMENT** `bit`
**Child Welfare Involvement** — `1` / `0`. If `1`, `TRAILS_IDENTIFIER` is required.
### Location Fields
**COUNTY\_RESIDENCE** `9(2)` *required*
**County of Residence** — 2-digit code. See [Counties](https://coloradobehavioralhealthadministration.mintlify.site/reference/appendix-a/counties.md). Use county of location if houseless. `77` = Out of State, `99` = Unknown (WM only).
**ZIPCODE\_RESIDENCE** `x(10)`
**Zip Code of Residence** — Format `99999` or `99999-9999`. Required unless County is `77` (Out of State) or `99` (Unknown).
Conditional
**LAST\_KNOWN\_ADDRESS\_LINE\_1** `x(100)`
**Last Known Address Line 1** — Text. Null for homeless/houseless and Out of State.
**LAST\_KNOWN\_ADDRESS\_LINE\_2** `x(100)`
**Last Known Address Line 2** — Text. Null for homeless/houseless and Out of State.
**LAST\_KNOWN\_CITY** `x(100)`
**Last Known City** — Text. Null for homeless/houseless and Out of State.
**RAE\_REGION** `9(1)`
**RAE Region** — `1`-`4`. Required if any part of admission treatment is Medicaid-funded.
Conditional
### 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.