logo
API docs by Redocly

Central Registry Discharge API (1.1.3)

Download OpenAPI specification:

Overview

The Central Registry Discharge API allows authorized users to discharge a patient from The Central Registry.

Purpose

  • This API facilitates the one-way synchronization of patient discharge records from a clinic software platform to The Central Registry, via an authenticated API connection.
  • It ensures compliance with internal policies by enforcing secure connection, data integrity, validation, and auditing steps.
  • The current version of the API will not allow updates to the clinic software from the Central Registry (callback) if the discharge initially occurs in the CR.

Key Features

  • Field Level Validation: Ensures that mandatory fields within the Central Registry including discharge dates, medications, comply with internal rules.
  • Authenticated Requests Only: Uses bearer token authentication to ensure only authorized users can submit discharges.
  • Detailed Responses: Provides easy to parse and understand JSON responses with errors and validation failures.
  • Logging & Auditing: Tracks all discharge submissions for auditing and accountability.

Assumptions & Requirements

  • The patient must be active in the clinic software platform and The Central Registry at the time of discharge.
  • The user submitting the request must be authorized user of the software platform with authority to discharge a patient.
  • The patient must have a valid CRID (Central Registry ID) in order to submit a discharge.
  • The discharge request is final and cannot be modified once submitted.

Authentication

The authentication process has two steps:

  1. You must use Basic authentication with your provided vendor username and password to obtain a temporary user token
  2. The user token can then be used to access other endpoints on the system

Login

Login to the Central Registry

Endpoint Overview

This endpoint allows an authorized user to login to The Central Registry and obtain an authentication token.

Key Notes

  • Basic Authentication (username and password) is required.
  • All fields in the request body are required.
  • The response includes a token that can be used for subsequent API calls.
Authorizations:
basicAuth
Request Body schema: application/json
required
first_name
required
string

First Name: The first name of the user.

last_name
required
string

Last Name: The last name of the user.

unique_site_id
required
string = 8 characters

Unique Site ID: An identifier that's composed of the 2-character short name for the state, and 6-digits that follow the first segment.

Responses

Request samples

Content type
application/json
{
  • "first_name": "Test",
  • "last_name": "User",
  • "unique_site_id": "DE434055"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "expires": "2023-12-31T23:59:59Z"
}

Discharge

Discharge a patient from the Central Registry

Endpoint Overview

This endpoint allows an authorized user to discharge a patient from The Central Registry.

Key Notes

  • All fields are required to process valid request.
  • Validation ensures compliance with internal rules.
  • The discharge process is final and cannot be modified.
  • The response includes success confirmation or detailed error messages.
Authorizations:
bearerAuth
Request Body schema: application/json
required
discharge_user_name
required
string

Discharge User Name: The full name of the user in the clinic software platform that is performing the discharge. This will be used for auditing purposes.

unique_site_id
required
string = 8 characters

Unique Site ID: An identifier that's composed of the 2-character short name for the state, and 6-digits that follow the first segment.

crid
required
string = 9 characters

Central Registry ID: A unique 9-character identifier for the patient in the Central Registry. Must be exactly 9 characters long.

identification_hash
required
string

Identification Hash: A hash of the birthdate using the separately provided secret key, to validate that the selected patient is correct.

Important Details:

  • The origin of the hash should be the patient's date of birth in ISO8601 format (YYYY-MM-DD)
  • The input hash must be in hex format for proper validation
  • The source method used for reference is hash_hmac() from PHP: https://www.php.net/manual/en/function.hash-hmac.php
  • This is a HMAC hash, the secret key must be used to create the hash for compatibility
discharge_date
required
string <date>

Actual date of discharge in ISO8601 format (YYYY-MM-DD).

  • Must not be null or blank.
  • Must not be in the future.
  • Must not be before the admit date of this episode in the Central Registry.
discharge_reason
required
integer

Reason for discharge, represented by an integer code.

The discharge reason “Patient did not complete the admission process” may ONLY be selected if the patient has not yet received any doses of medication in this episode.

Must be one of the provided codes:

  • 1 → No specific reason recorded.
  • 2 → Patient successfully completed treatment.
  • 3 → Patient transferred to another OTP/MAT program.
  • 4 → Patient deceased.
  • 5 → Unable to contact or lost contact with the patient.
  • 6 → Patient left against medical advice.
  • 7 → Patient was incarcerated.
  • 8 → Patient lost funding or insurance.
  • 9 → Patient discharged due to medical reasons or hospitalization.
  • 10 → Patient was non-compliant or administratively discharged.
  • 11 → Presumed dead, not yet confirmed.
  • 12 → Patient did not complete the admission process (only allowed if no medication was given).
  • 13 → Patient transferred due to job-related reasons.
  • 14 → Discharged before converting to Lighthouse CR.
  • 15 → Death due to COVID-19.
  • 16 → Death due to overdose.
  • 17 → Clinic permanently closed.
  • 18 → Transferred to an OBOT or prescription-based program.
  • 19 → Transferred to a higher level of care.
  • 20 → Transferred to another incarceration facility.
  • 21 → Patient was released from jail or prison.
  • 22 → Unknown or not collected.
  • 23 → Transferred to an outpatient program.
  • 24 → Transferred to a residential program.
  • 25 → Leaving mobile unit for another OTP.
dose_through_date
required
string <date>

Date of the last medication physically provided including take homes (YYYY-MM-DD).

  • Must not be before the admit date.
  • Can be after discharge date for take-home doses.
  • Can not be NULL or blank.
medication
required
integer

Medication code corresponding to the final dose.

Only one medication can be selected.

If the final dose was split, list only once.

Can not be NULL or blank.

Must correspond to one of these codes:

  • 1 → Methadone.
  • 2 → Suboxone.
  • 3 → Subutex.
  • 4 → Naltrexone.
  • 5 → Buprenorphine.
  • 6 → Vivitrol.
  • 7 → No medication given.
  • 8 → Probuphine.
  • 9 → Sublocade.
  • 10 → Zubsolv.
  • 12 → No medication administered during treatment.
dosage
required
number <float>

Final dose provided (in milligrams).

  • Must be up to 3 digits with up to 2 decimals.
  • If no medication was given, this should be 0.
  • If the final dose was split, provide the total amount.
modality
integer

Treatment Modality

Only one modality can be selected.

Optional field, if the field is provided in the payload, it cannot be set to NULL.

Must correspond to one of these codes:

  • 1 → Maintenance
  • 2 → Short term detox (< 30 days)
  • 3 → Long term detox (< 6 months)
dosage_step
integer

Patient's Step Level

Only one step level can be selected.

Optional field, if the field is provided in the payload, it cannot be set to NULL.

Must correspond to one of these codes:

  • 0 → 0
  • 1 → A1
  • 2 → 1
  • 3 → 2
  • 4 → 3
  • 5 → 4
  • 6 → 5
  • 7 → 6
  • 8 → 13
  • 9 → 27
employment
integer

Employment Type

Only one employment type can be selected.

Optional field, if the field is provided in the payload, it cannot be set to NULL.

Must correspond to one of these codes:

  • 1 → Full time (35+ hours)
  • 2 → Part time (regular hours)
  • 3 → Part time (irregular hours)
  • 4 → Student
  • 5 → Military service
  • 6 → Retired / disability
  • 7 → Unemployed
  • 8 → Controlled environment
  • 9 → Homemaker
housing
string

Housing Arrangements

Only one housing option can be selected.

Optional field, if the field is provided in the payload, it cannot be set to NULL.

Must correspond to one of these codes:

  • owns → Owns
  • dependent → Lives with someone else long term - making no payments
  • rents → Rents
  • transient → Transient - no permanent home address
  • shelter → Shelter
arrests
integer

Number of arrests in the past 90 days

Only one option can be selected.

Optional field, if the field is provided in the payload, it cannot be set to NULL.

Must correspond to one of these codes:

  • 0 → None
  • 1 → 1-2 arrests
  • 2 → 3-5 arrests
  • 3 → More than 5 arrests
has_appointment_scheduled
boolean

Whether the patient has a follow-up appointment scheduled or not.

  • Must be a boolean value
  • Can not be NULL, but is optional
appointment_scheduled_date
string <date>

Date of the follow-up appointment which has been scheduled.

  • Can only be provided if the previous field is TRUE.
  • If the previous field is TRUE, the date must not be NULL or blank.

Responses

Request samples

Content type
application/json
{
  • "discharge_user_name": "John Doe",
  • "unique_site_id": "AL123456",
  • "crid": "123456789",
  • "identification_hash": "52eaa2f1ad9cf031577c3b072e77ac5fe6491af3ee21646d665b9449f253a333",
  • "discharge_date": "2023-12-01",
  • "discharge_reason": 2,
  • "dose_through_date": "2019-08-24",
  • "medication": 1,
  • "dosage": 108.32,
  • "modality": 0,
  • "dosage_step": 0,
  • "employment": 0,
  • "housing": "string",
  • "arrests": 0,
  • "has_appointment_scheduled": true,
  • "appointment_scheduled_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Discharge recorded successfully."
}