šŸŒ External Patient Onboarding & Portal Access API Guide

šŸŒ External Patient Onboarding & Portal Access API Guide

šŸŒ External Patient Onboarding & Portal Access API Guide

This guide explains how to integrate with the External Patient Onboarding and Portal Access system.

šŸ” Credentials & Required Configuration

Before you can use this integration, youā€™ll need the following provided to you in advance:

KeyDescription
[APPLICATION_URL]The base URL of the application you are integrating with
[API_USERNAME]The Basic Auth username
[API_PASSWORD]The Basic Auth password
[TREATMENT_TYPE]The treatment type for the patient (e.g., "Weight-loss")
[CENTRAL_PHARMACY_ID]The unique pharmacy ID assigned to your clinic (e.g., "pharm123")

Replace all placeholder values in the examples below with your actual values.

šŸ“„ 1. Create a User & Get a Portal Access URL

Use this endpoint to create a new patient record and generate a single sign-on (SSO) style URL that logs them directly into the portal to complete their questionnaire and begin their telemedicine visit.

Endpoint:

POST [APPLICATION_URL]/external-transfer-onboarding

Headers:

  • Content-Type: application/json

  • Accept: application/json

  • Authorization: Basic [BASE64_ENCODED_API_USERNAME:PASSWORD]

Example curl Command:

curl -X POST [APPLICATION_URL]/external-transfer-onboarding \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $(echo -n '[API_USERNAME]:[API_PASSWORD]' | base64)" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "1234567890",
    "address": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "12345",
    "height_feet": "5",
    "height_inches": "10",
    "weight": "180",
    "sex": "Male",
    "dob": "1990-01-01",
    "treatment_type": "[TREATMENT_TYPE]",
    "central_pharmacy_id": "[CENTRAL_PHARMACY_ID]"
  }'

Response Example:

{
  "status": "success",
  "user_id": 36,
  "access_token": "abc123xyz456",
  "redirect_url": "https://tenant-domain.com/telemed/visit?token=abc123xyz456"
}

Important:

  • Store both the user_id and access_token.

  • Use the redirect_url immediately to log the user into the patient portal.

  • Tokens are one-time-use and may expire after a limited time.

šŸš« 2. Revoke a Userā€™s Access Token

If a user should no longer have portal access, you can revoke their token.

Endpoint:

POST [APPLICATION_URL]/external-portal-access/revoke

Example curl Command:

curl -X POST [APPLICATION_URL]/external-portal-access/revoke \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $(echo -n '[API_USERNAME]:[API_PASSWORD]' | base64)" \
  -d '{
    "user_id": 36,
    "reason": "Testing revocation"
  }'

šŸ”„ 3. Re-Enable a Userā€™s Portal Access

You can issue a new token for a previously revoked or expired user.

Endpoint:

POST [APPLICATION_URL]/external-portal-access/enable

Example curl Command:

curl -X POST [APPLICATION_URL]/external-portal-access/enable \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $(echo -n '[API_USERNAME]:[API_PASSWORD]' | base64)" \
  -d '{
    "user_id": 36,
    "valid_for_hours": 24
  }'

You will receive a new redirect_url and access_token to send the user back into the portal.



šŸ“† 4. Creating a Follow-Up Entry for a Patient

Once a patient has completed their initial onboarding and telemedicine visit, your system may want to trigger a follow-up event inside the Nimbus platform.

To do this, you'll first need to determine which order the follow-up should be linked to.

šŸ” Step 1: Retrieve the Patientā€™s Latest Order

Before you can create a follow-up, you must retrieve the most recent order associated with the patient.

Endpoint:

GET [APPLICATION_URL]/external-portal-access/latest-order?user_id=[USER_ID]

Example curl Command:

curl -X GET "[APPLICATION_URL]/external-portal-access/latest-order?user_id=36" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $(echo -n '[API_USERNAME]:[API_PASSWORD]' | base64)"

Example Response:

{
  "status": "success",
  "data": {
    "order_id": 789,
    "user_id": 36,
    "patient_id": 45,
    "tenant_domain": "my.youvii.test"
  }
}

šŸ“ Step 2: Create the Follow-Up

Once you've retrieved the correct order data, you can use it to generate a follow-up entry.

Endpoint:

POST [APPLICATION_URL]/external-portal-access/create-followup

Required Fields:

FieldDescription
followup_dateThe scheduled date for the follow-up (ISO format: YYYY-MM-DD)
patient_idProvided from the latest order response
user_idProvided from the latest order response
tenant_domainProvided from the latest order response

Example curl Command:

curl -X POST [APPLICATION_URL]/external-portal-access/create-followup \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $(echo -n '[API_USERNAME]:[API_PASSWORD]' | base64)" \
  -d '{
    "followup_date": "2024-04-01",
    "patient_id": 45,
    "user_id": 36,
    "tenant_domain": "my.youvii.test"
  }'

Example Response:


{
  "message": "Followup created successfully",
  "data": {
    "followup_id": 123,
    "patient_id": 45,
    "user_id": 36,
    "followup_date": "2024-04-01",
    "tenant_domain": "my.youvii.test"
  }
}

āš™ļø Additional Notes

  • Basic Authentication uses base64 encoding of [API_USERNAME]:[API_PASSWORD].

  • All responses are in JSON.

  • Tokens are tenant- and user-specific, one-time-use, and may expire.

  • You must receive the required configuration values ahead of time to use these endpoints properly.