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

Currently, Bearer token authentication will be used. This token will be provided to the vendor by the Central Registry, and will be registered into the CR's database.

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.

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
}

Response samples

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