Data Model

Three resources drive every partner integration: Organizations, Staff, and Clients. This page summarizes the data you need to send when creating, updating, or deactivating each — and how the three relate to one another.

How the resources relate

Network (a group of organizations, e.g. "Montana Drug Court")
 └── Organization (a single program or agency)
      ├── Staff (admins + staff users within the organization)
      └── Clients (the people the organization serves)
            └── Assessments (REC-CAP rounds tied to a client)
                 └── Recovery Plan
                      └── Goals / Tasks

A client can exist at more than one organization over time (re-enrollment, referrals across programs). The stable identifier is client_uuid— one per person, reused across organizations. Each enrollment at a specific organization is a client_id.

Organizations

An Organization is a single program or agency — one billing contract, one set of staff, one caseload of clients. Partners with a network-scoped API key can create multiple organizations; partners with an org-scoped key work inside one.

Network membership is implicit from your API key

There is no network_idfield in the create-organization request. The organization is automatically created within whichever network your API key is scoped to. You don't need to know or supply a network identifier.

If you work with more than one network (e.g. MARR plus another), you'll be issued one API key per network. Same code on your side — different environment variable.

Create an organization

POST /v1/organizations— requires a network-scoped API key.

Field	Required	Notes
name	Yes	Display name shown in reports and exports
address, city, state, zip	No	Used on printed assessment results and the org profile
phone	No	Same
admin_email	No	Primary admin contact. If you also want to provision the first staff user, call `POST /v1/staff` after creating the org.

Update an organization

PATCH /v1/organizations/{id}— any subset of the same fields. All fields optional; only provided fields update.

Deactivate an organization

POST /v1/organizations/{id}/deactivate— suspends the organization.

After deactivation: staff users can no longer log in, iframe embeds for that org return 403, webhooks stop firing for that org's clients. Client data is preserved (not deleted), and the org can be reactivated on request. Active clients are not auto-discharged; if you need to end their enrollments, call POST /v1/clients/{id}/discharge first.

Staff

Staff users work inside an organization. They can be admins (manage the organization) or regular staff (work with clients). Each staff user has a permission matrix scoping what they can see and change.

Create a staff user

POST /v1/staff— scoped to the calling API key's organization, or pass X-Organization-Id header with a network-scoped key.

Field	Required	Notes
email	Yes	Must be unique per org. Used as the login identifier.
first_name, last_name	Yes	Shown in caseload lists and assignment selectors
role	Yes	Either `admin` or `staff`. Admins can manage the org; staff work with clients.
permissions	No	See permission matrix below. Defaults: `view` for clients/assessments/goals, `none` for staff/settings.

No invitation email is sent.As with any partner-provisioned user, onboarding is the partner's responsibility. Partner issues login via their own flow and surfaces RCMS via embed tokens.

Permission matrix

Per-domain access level, each one of: none, view, edit, full.

Domain	Controls
clients	Client list, profile, intake, discharge
assessments	Creating, viewing, scoring, printing assessments
goals	Recovery plans, goal templates, goal creation/edit
staff	Staff list, inviting, deactivating other staff
settings	Organization configuration, programs, tags, integrations

Update a staff user

PATCH /v1/staff/{id}— change name or role. Email is immutable; create a new staff user if someone's email changes.

PUT /v1/staff/{id}/permissions— replace the full permission matrix.

Deactivate a staff user

POST /v1/staff/{id}/deactivate— ends the staff member's access.

Effect is immediate: login denied, iframe embed tokens signed for that staff user start returning 403, outstanding tokens get rejected by RLS on the next query. Caseload assignments are preserved (for historical reporting); reassign clients via PATCH /v1/clients/{id} before or after deactivation.

Clients

Clients are the people an organization serves. Creating a client is called enrollment; ending their engagement is discharge. Returning clients get readmitted.

Enroll a client

POST /v1/clients

Enrollment runs a three-level fuzzy match so you can safely enroll anyone without duplicating. RCMS always returns a client back — either created (new record) or matched (existing person, same client_uuid reused for cross-org continuity). No review step required on the partner side.

Field	Required	Notes
first_name, last_name	Yes	Used for matching and display
date_of_birth	Yes	ISO date (`YYYY-MM-DD`). Core match field.
sex	Yes	Sex at birth: `male`, `female`, `other`. Used in matching.
race	Yes	Free-text or comma-separated for multi-race. Required for SAMHSA-style reporting.
ethnicity	Yes	Hispanic/Latino / Not / Prefer not to say
admission_date	Yes	When the client started at this org
email, phone	Recommended	Used for Level 1 & 2 fuzzy matching. Missing both forces a Level 3 (name + DOB + sex) match.
gender_identity	Optional	Separate from sex at birth
priority_populations	Optional	Array: veteran, justice_involved, pregnant, homeless, lgbtq, iv_drug_user, etc.
referral_source	Optional	How they found the org. Useful for reporting, not required for enrollment.
moud_status	Optional	Current MOUD/MAT medication if applicable

Missing any recommended field results in intake_complete: false on the client record — staff can fill in the rest inside the iframe later. This lets partners enroll fast without blocking on data they don't yet have.

Update a client

PATCH /v1/clients/{id}— any subset of the enrollment fields except the identifying ones (name, DOB, sex). Those are immutable via API; if there was a typo, staff can correct it inside the iframe after identity verification.

Discharge a client

POST /v1/clients/{id}/discharge

Discharge is the “deactivate” action for a client. It ends the enrollment but preserves history (client_uuidis retained so if they come back, it's the same person).

Field	Required	Notes
discharge_date	Yes	ISO date
discharge_reason	Yes	Enum: completed_program, transferred, left_against_advice, incarcerated, deceased, other
destination	Optional	Where the client is going (housing, treatment facility, etc.). Supports continuity-of-care reporting.

Readmit a client

POST /v1/clients/{id}/readmit— starts a new episode at the same organization. Previous assessment history is preserved and linked to the new episode automatically.