Subscription Management

Overview

The Subscription Management API calls help Bridge Health maintain a system of record for program participation in CBO-sponsored weight-loss and metabolic health programs. They enforce program availability rules, tracks subscription enrollment status, and ensure provider-to-program credentialing compliance. The API prevents downstream failures, ensures regulatory compliance, and provides auditable records for telehealth platforms integrating with Community-Based Organizations (CBOs).

Bridge Health operates on non-identifiable references and does not store or process PHI—a deliberate architectural boundary to minimize HIPAA scope while maintaining compliance with AKS, HIPAA, and 340B regulations. The API uses JSON over HTTPS with bearer-token authentication.

API Integration Points and Workflow

1. Patient Program Availability Confirmation

Objective: Determine whether a patient can access a specific CBO program based on geographic ZIP code location and insurance type before any clinical workflow begins.
API Call Triggered: checkProgramAvailability
Business Impact:
- Prevents downstream clinical, pharmacy, or billing errors by verifying availability before medical intake begins. This pre-clinical check avoids wasted clinical time and potential compliance issues.
- Available patients proceed to the remainder of the enrollment workflow.
- API responses include participating pharmacies and out-of-pocket medication costs for the subsequent medication and pharmacy selection step and a list credentialed providers that the patient could be matched with.

Bridge Health Operations - Program Availability

2. Medication and Pharmacy Preference Selection

Objective: Allow patients to select their medication preference and pharmacy through the telehealth platform's UI, ensuring patient autonomy without inducement towards specific pharmacies or medications.
API Call Triggered: None (this step utilizes information from the checkProgramAvailability response)
Business Impact:
- Ensures patient-driven selection to comply with anti-inducement regulations, reducing regulatory and legal risks.
- The telehealth platform displays medication options, pharmacies, and pricing from the checkProgramAvailability API call.

Bridge Health Operations - Medication and Pharmacy Preference

3. Enrolling a Patient

Objective: Activate the patient's subscription (set state to ACTIVE) in the chosen weight-loss program. Bridge Health serves as the system of record for this subscription state.
API Call Triggered: enroll
Business Impact:
- Activates subscription state (ACTIVE), enabling pharmacy fulfillment, provider care continuity, and program-level reporting.
- Provides auditable records required by CBOs for financial reporting and regulatory compliance.

Bridge Health Operations - Enroll and Checkout

4. Provider Verification

Objective: Verify that a provider is credentialed by the CBO for a specific program before allowing that provider to treat patients enrolled in that program. Credentialing is program-specific, not global — a provider must be credentialed for each CBO program separately.
API Call Triggered: verifyProviderCBOCredentialing
Business Impact:
- Prevents uncredentialed providers from treating program patients, ensuring prescriptions are legally valid and mitigating compliance violations and legal risks.
- Enforces provider ↔ CBO ↔ program alignment, ensuring only properly credentialed providers can treat program patients.

Bridge Health Operations - Provider Credentialing

5. Cancellation and Disenrollment

Objective: Deactivate the patient's subscription (set state from ACTIVE to INACTIVE) based on patient decision, medical necessity, or administrative criteria. This prevents further program benefits and ensures billing, pharmacy, and reporting correctness.
API Call Triggered: disenroll
Business Impact:
- Deactivates subscription state (ACTIVE → INACTIVE), preventing incorrect billing, pharmacy fulfillment, and program reporting. Without this, downstream systems may continue processing benefits for unavailable patients.
- Provides auditable disenrollment records with clear reasons for CBO compliance tracking and financial reporting.
- Ensures pharmacy and prescriber systems can verify that medication dispensing and follow-up care should be discontinued.

POST `/checkProgramAvailability`

Purpose: Determine whether the GLP-1 Weight-Loss Program is offered to a prospective patient.
Auth: Authorization: Bearer <access_token>
Content-Type: application/json
Idempotent: Yes (same input ⇒ same outcome).

Request body schema

Field	Type	Required	Example	Notes
`zipCode`	string	Yes	`"75035"`	5-digit U.S. ZIP
`insuranceType`	string	Yes	`"Commercial"`	Enum: `Commercial` \| `Government` \| `Medicare` \| `Medicaid` \| `SelfPay` (confirm full list)

{
  "zipCode": "75035",
  "insuranceType": "Commercial"
}

Success response `200 OK` — Program Available

{
    "data": {
        "cbos": [
            {
                "cboID": 1,
                "cbo_drugs": [
                    {
                        "cboDrugID": 1,
                        "cboID": 1,
                        "cboName": "Community Health Center 1",
                        "cboSubsidy": 2.0,
                        "cost": 20.0,
                        "description": "Used to lower cholesterol and reduce the risk of heart disease.",
                        "drugID": 1,
                        "drugName": "Atorvastatin (Lipitor)",
                        "manufacturerSubsidy": 2.0,
                        "status": "active"
                    },
                    {
                        "cboDrugID": 2,
                        "cboID": 1,
                        "cboName": "Community Health Center 2",
                        "cboSubsidy": 1.5,
                        "cost": 15.5,
                        "description": "Used to treat type 2 diabetes.",
                        "drugID": 2,
                        "drugName": "Metformin (Glucophage)",
                        "manufacturerSubsidy": 1.5,
                        "status": "active"
                    },
                    {
                        "cboDrugID": 3,
                        "cboID": 1,
                        "cboName": "Community Health Center 3",
                        "cboSubsidy": 1.2,
                        "cost": 12.0,
                        "description": "Used to treat high blood pressure and angina.",
                        "drugID": 3,
                        "drugName": "Amlodipine (Norvasc)",
                        "manufacturerSubsidy": 1.2,
                        "status": "active"
                    }
                ],
                "credentialedPrescriberNPIs": [
                    {
                        "NPI": "NPI002",
                        "name": "Jane Smith",
                        "prescriberID": 2
                    }
                ],
                "name": "Community Health Center 4",
                "pharmacies": [
                    {
                        "pharmacyID": 2,
                        "pharmacyName": "CHC Pharmacy 2"
                    },
                    {
                        "pharmacyID": 5,
                        "pharmacyName": "CHC Pharmacy 4"
                    }
                ]
            }
        ],
        "determinationReason": "Available",
        "available": true
    },
    "message": "Program is available",
    "success": true
}

Success response `200 OK` — Program Unavailable due to Insurance Type

{
    "data": {
        "cbos": [],
        "available": false,
        "reason": "Unavailable due to insurance type"
    },
    "message": "Program is unavailable",
    "success": true
}

Success response `200 OK` — Program Unavailable due to Zip Code

{
    "data": {
        "cbos": [],
        "available": false,
        "reason": "Unavailable due to zip code"
    },
    "message": "Program is unavailable",
    "success": true
}

Success response `200 OK` — Program Unavailable due to BOTH Insurance Type and Zip Code

{
    "data": {
        "cbos": [],
        "available": false,
        "reason": "Unavailable due to zip code and Insurance Type"
    },
    "message": "Program is unavailable",
    "success": true
}

Error Responses for POST /checkProgramAvailability

400 Bad Request

This error occurs due to one or more required fields being missing or malformed

Example: Missing Zip Code

{
    "error": {
        "code": "BAD_REQUEST",
        "details": "Missing required fields: Patient Zip Code"
    },
    "message": "Bad request",
    "success": false
}

401 Unauthorized

This error occurs when there is a missing/invalid bearer token (see global Auth section).

404 Not Found

This error occurs when the endpoint path is incorrect and is presented as a standard 404 HTML/JSON response from the gateway.

Code Examples

curl

curl --location 'https://sandbox-api.bridgehealthhub.com/checkProgramAvailability' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '
{
    "zipCode": "75035",
    "insuranceType": "Commercial"
}'

POST `/verifyProviderCBOCredentialing`

Purpose: Check whether a tele health provider is credentialed with a given CBO.
Auth: Authorization: Bearer <access_token>
Content-Type: application/json
Idempotent: Yes – the same input always yields the same credentialing result.

Request body

Field	Type	Required	Notes
`prescriberID`	integer	Yes	Internal ID of the provider requesting enrolment.
`cboID`	integer	Yes	Target CBO.

{
    "prescriberID": 1,
    "cboID": 1
}

Success `200 OK` — Provider is credentialed

{
    "data": {
        "credentialedPrescriberNPIs": [
            {
                "NPI": "NPI001",
                "name": "Jane Credentialed",
                "prescriberID": 2
            },
            {
                "NPI": "NPI001",
                "name": "Jane Credentialed",
                "prescriberID": 1
            }
        ],
        "available": true
    },
    "message": "Provider is credentialed with CBO",
    "success": true
}

data is an array of CredentialedPrescriberNPIs objects for all providers credentialed with the CBO, including the requester.

Success `200 OK` — **Provider is not credentialed**

{
    "data": {
        "credentialedPrescriberNPIs": [
            {
                "NPI": "NPI001",
                "name": "Jane Credentialed",
                "prescriberID": 1
            },
            {
                "NPI": "NPI002",
                "name": "Jane Smith",
                "prescriberID": 2
            }
        ]
    },
    "message": "Provider is not credentialed with CBO",
    "success": true
}

Field	Type	Notes
`data.credentialedPrescriberNPIs`	array	List of providers who are credentialed with the CBO so the caller can select an alternative.

Error Responses for POST `/verifyProviderCBOCredentialing`

400 Bad Request

This error occurs when one or more required fields are missing/invalid

{
    "error": {
        "code": "BAD_REQUEST",
        "details": "Missing required fields: TH Co ID, Cbo ID  are mandatory.."
    },
    "message": "Bad request",
    "success": false
}

401 Unauthorized

This error occurs when there is a missing/invalid bearer token (see global Auth section).

404 Not Found

This error occurs when the endpoint path is incorrect and is presented as a standard 404 HTML/JSON response from the gateway.

Code Examples

curl

curl --location 'https://sandbox-api.bridgehealthhub.com/verifyProviderCBOCredentialing' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "prescriberID": 1,
    "cboID": 1
}'

POST `/enroll`

Purpose: Enroll a patient in a CBO's GLP-1 weight-loss program. This call also internally runs /checkProgramAvailability (to ensure program availability) and, if the request includes a prescriberID, verifies provider credentialing.
Auth: Authorization: Bearer <access_token>
Content-Type: application/json
Idempotent: No – a second call for the same patient/CBO returns a 409 Conflict error.

Request body schema

Field	Type	Required	Notes
`thcoPatientID`	string	Yes	Tele-health platform's patient identifier (opaque to this API).
`cboID`	integer	Yes	Target CBO for enrollment.
`insuranceType`	string	Yes	`"Commercial"` \| `"Government"`
`zipCode`	string	No	5-digit U.S. ZIP code.
`pharmacyID`	string	No	Target Pharmacy ID for enrollment.

{
    "thcoPatientID": "10",
    "cboID": 1,
    "pharmacyID": "1",
    "insuranceType": "Commercial",
    "zipCode": "75034"
}

Success `201 Created` — User enrolled successfully

{
    "data": {
        "credentialedPrescriberNPIs": [
            {
                "NPI": "NPI002",
                "name": "Jane Smith",
                "prescriberID": 2
            },
            {
                "NPI": "NPI001",
                "name": "Jane Credentialed",
                "prescriberID": 1
            }
        ],
        "patient": {
            "cboID": 1,
            "cboName": "Community Health Center 1",
            "cboPatientID": null,
            "createdBy": null,
            "createdDate": "2025-07-29T05:12:56",
            "isActive": true,
            "patientID": 1905,
            "reason": null,
            "status": "ENROLLED",
            "thcoID": 8,
            "thcoName": "Telehealth postman",
            "thcoPatientID": "THCO-8776d8",
            "updatedBy": null,
            "updatedDate": "2025-07-29T05:12:56"
        }
    },
    "message": "User enrolled successfully",
    "success": true
}

Field	Type	Notes
`data.credentialedPrescriberNPIs`	array	List of all credentialed providers for this CBO.
`data.patient`	Patient	The newly enrolled patient record.
See Data Models section for definitions of CredentialedPrescriberNPI and Patient.

Conditional `200 OK` — Program Unavailable

If enrollment fails due to program unavailability (ZIP + insurance combo), you receive a successful envelope with available = false:

{
    "data": {
        "cbos": [],
        "available": false,
        "reason": "Unavailable due to insurance type"
    },
    "message": "Program is Unavailable",
    "success": true
}

Error Responses for POST `/enroll`

`409 Conflict` - Patient Already Enrolled

If a request is made to enroll a patient with a tchoPatientID that is already actively enrolled in a program, this error response will be given with the message "patient is already enrolled".

{
    "error": {
        "code": "Conflict",
        "details": "patient is already enrolled."
    },
    "message": "Conflict",
    "success": false
}

`400 Bad Request` - Invalid Zip Code

If a request is made to enroll a patient with a zip code that does not contain the necessary 5 digits that would be expected from a typical zip code.

{
    "error": {
        "code": "BAD_REQUEST",
        "details": "Invalid length for fields: Patient Zip Code (length 4, expected min 5 to max 5)"
    },
    "message": "Bad request",
    "success": false
}

`400 Bad Request` - Invalid CBO ID

If a request is made to enroll a patient with a CBO ID that is not an integer.

{
    "error": {
        "code": "BAD_REQUEST",
        "details": "Invalid type for fields: CBO ID (expected int)"
    },
    "message": "Bad request",
    "success": false
}

`400 Bad Request` - Missing Required Fields

If a request is made to enroll a patient with one of the required fields missing.

{
    "error": {
        "code": "BAD_REQUEST",
        "details": "Missing required fields: Patient Zip Code, CBO ID"
    },
    "message": "Bad request",
    "success": false
}

`401` Unauthorized

This error occurs when there is a missing/invalid bearer token (see global Auth section).

`404` Not Found

This error occurs when the endpoint path is incorrect and is presented as a standard 404 HTML/JSON response from the gateway.

Code Examples

curl

curl --location 'https://sandbox-api.bridgehealthhub.com/enroll' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "thcoPatientID": "THCO99",
    "cboID": 1,
    "pharmacyID": "1",
    "insuranceType": "Commercial",
    "zipCode": "75034"
}
'

POST `/disenroll`

Purpose: Disenroll an actively enrolled patient from a CBO's GLP-1 weight-loss program
Auth: Authorization: Bearer <access_token>
Content-Type: application/json
Idempotent: No – calling this a second time for the same patient yields a 400 Bad Request error

Request Body Schema

Field	Type	Required	Notes
`thcoPatientID`	string	Yes	Telehealth platform's patient identifier.
`reason`	string	No	Human-readable reason for disenrollment.

{
  "thcoPatientID": "10",
  "reason": "No longer want to continue therapy"
}

Success `200 OK` — User is disenrolled

{"reason": "No longer want to continue therapy", "thcoPatientID": 10}

{
    "data": {},
    "message": "User is disenrolled",
    "success": true
}

Error Responses for POST `/disenroll`

`400 Bad Request` - Patient was not Enrolled

{
    "error": {
        "code": "BAD_REQUEST",
        "details": "patient is not enrolled"
    },
    "message": "Bad request",
    "success": false
}

`400 Bad Request` - Missing `thcoPatientID`

{
    "error": {
        "code": "BAD_REQUEST",
        "details": "patient id is not provided"
    },
    "message": "Bad request",
    "success": false
}

Code Examples

curl

curl --location 'https://sandbox-api.bridgehealthhub.com/disenroll' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{"reason": "not interested", "thcoPatientID": "THCO99"}'

Subscription Management

Overview

API Integration Points and Workflow

1. Patient Program Availability Confirmation

2. Medication and Pharmacy Preference Selection

3. Enrolling a Patient

4. Provider Verification

5. Cancellation and Disenrollment

POST /checkProgramAvailability

Request body schema

Success response 200 OK — Program Available

Success response 200 OK — Program Unavailable due to Insurance Type

Success response 200 OK — Program Unavailable due to Zip Code

Success response 200 OK — Program Unavailable due to BOTH Insurance Type and Zip Code

Error Responses for POST /checkProgramAvailability

400 Bad Request

Example: Missing Zip Code

401 Unauthorized

404 Not Found

Code Examples

curl

POST /verifyProviderCBOCredentialing

Request body

Success 200 OK — Provider is credentialed

Success 200 OK — Provider is not credentialed

Error Responses for POST /verifyProviderCBOCredentialing

400 Bad Request

401 Unauthorized

404 Not Found

Code Examples

curl

POST /enroll

Request body schema

Success 201 Created — User enrolled successfully

Conditional 200 OK — Program Unavailable

Error Responses for POST /enroll

409 Conflict - Patient Already Enrolled

400 Bad Request - Invalid Zip Code

400 Bad Request - Invalid CBO ID

400 Bad Request - Missing Required Fields

401 Unauthorized

404 Not Found

Code Examples

curl

POST /disenroll

Request Body Schema

Success 200 OK — User is disenrolled

Error Responses for POST /disenroll

400 Bad Request - Patient was not Enrolled

400 Bad Request - Missing thcoPatientID

Code Examples

curl

POST `/checkProgramAvailability`

Success response `200 OK` — Program Available

Success response `200 OK` — Program Unavailable due to Insurance Type

Success response `200 OK` — Program Unavailable due to Zip Code

Success response `200 OK` — Program Unavailable due to BOTH Insurance Type and Zip Code

POST `/verifyProviderCBOCredentialing`

Success `200 OK` — Provider is credentialed

Success `200 OK` — **Provider is not credentialed**

Error Responses for POST `/verifyProviderCBOCredentialing`

POST `/enroll`

Success `201 Created` — User enrolled successfully

Conditional `200 OK` — Program Unavailable

Error Responses for POST `/enroll`

`409 Conflict` - Patient Already Enrolled

`400 Bad Request` - Invalid Zip Code

`400 Bad Request` - Invalid CBO ID

`400 Bad Request` - Missing Required Fields

`401` Unauthorized

`404` Not Found

POST `/disenroll`

Success `200 OK` — User is disenrolled

Error Responses for POST `/disenroll`

`400 Bad Request` - Patient was not Enrolled

`400 Bad Request` - Missing `thcoPatientID`