Skip to content
This repository was archived by the owner on Dec 20, 2024. It is now read-only.

Patient Management

Jump to bottom
Adrian Valor edited this page Oct 20, 2022 · 21 revisions

There are many things you can do with patients and the below calls should cover most of what you need to get users into our system and manage them. You'll need to be logged in as a clinician or admin with the correct roles in order to use these calls.

Checking For Patient by E-Mail Address

Before creating a patient or trying to manipulate a patient, it is very helpful to verify that they aren't already in the system and get their internal patient ID number. Accounts are set up based on a unique e-mail address, which is used for login.

To use this endpoint, make a get request to v2/admin/patients. Include the query string value email with the e-mail address you are checking. If a patient is found, their basic profile information is returned. If the patient does not exist, an error message is returned indicating such.

Example:

The following example shows us checking for a patient account with the e-mail address of patient@example.com.

Request

GET https://sandbox.connectedcare.md/api/v2/admin/patients?email=patient@example.com

Headers Sent:

  • X-Developer-Id: ****
  • Authorization: Bearer ****
  • X-Api-Key: ****

Response (User Found)

Response Code (Success): 200 OK

{
  "data": {
    "patientId": 3381,
    "firstName": "Example",
    "lastName": "Patient",
    "email": "patient@example.com",
    "dob": "1981-12-10T01:01:01Z",
    "address": "121 W Lexington Dr, Glendale, CA 91203",
    "addressObject": {
         "line1": "121 W Lexington Drive",
         "line2": "Suite 412",
         "city": "Glendale",
         "state": "CA",
         "stateCode": "CA",
         "postalCode": "91203",
         "countryCode": "US",
         "country": "US",
         "addressText": "121 W Lexington Dr, Glendale, CA 91203"
      },
    "countryId": 1,
    "timeZoneId": 83,
    "mobileNumberWithCountryCode": "+1-555-555-1212",
    "gender": "M"
  },
  "success": true
}

Response (No Such User)

Response Code (User Not Found): 404 Not Found

"Patient user not found."

Getting Patient Profile Information

You can check the data the Virtual Consultation Management system has about a patient once you know their internal patient ID. Information includes basic and full profile, medical history, and other related data.

To use this endpoint, make a get request to v2/patients/profile/PATIENT_ID, where "PATIENT_ID" is the internal ID number of the patient in the VCM platform. Include the query string value include with one of the following words, which indicate the profile detail you want to see: "AccountDetails, Physician, Pharmacy, Anatomy, Addresses, Identifiers, Locations, Consultations, Tracking, All". If a patient with the ID exists in your account, the requested information is returned. If the patient does not exist, a 404 error will be returned.

Example:

The following example shows us requesting address info for the patient with ID 3381.

Request

GET https://sandbox.connectedcare.md/api/v2/patients/profile/3381?include=addresses

Headers Sent:

  • X-Developer-Id: ****
  • Authorization: Bearer ****
  • X-Api-Key: ****

Response (User Found)

Response Code (Success): 200 OK

{
  "data": [
    {
      "_dob": "1981-04-28T00:00:00Z",
      "address": "121 W Lexington Dr, Glendale, CA 91203",
      "addressObject": {
         "line1": "121 W Lexington Drive",
         "line2": "Suite 412",
         "city": "Glendale",
         "state": "CA",
         "stateCode": "CA",
         "postalCode": "91203",
         "countryCode": "US",
         "country": "US",
         "addressText": "121 W Lexington Dr, Glendale, CA 91203"
      },
      "addresses": [
        {
          "addressText": "121 W Lexington Dr, Glendale, CA 91203",
          "isActive": true
        }
      ],
      "country": "1",
      "countryCode": "+1",
      "createDate": "0001-01-01T00:00:00Z",
      "dob": "4/28/1981",
      "gender": "M",
      "homePhone": "",
      "lastName": "TestPatient",
      "mobilePhone": "+1-555-555-1234",
      "patientName": "John",
      "schoolContact": "",
      "schoolName": "",
      "personId": "3fbcfe23-7f18-4222-809a-2a9af209c118"
    }
  ],
  "total": 1
}

Example:

The following example shows us requesting locations info for the patient with ID 2806.

Request

GET https://sandbox.connectedcare.md/api/v2/patients/profile/2806?include=locations

Headers Sent:

  • X-Developer-Id: ****
  • Authorization: Bearer ****
  • X-Api-Key: ****

Response (User Found)

Response Code (Success): 200 OK

{
  "data": [
    {
      "addressObject": {
        "line1": "",
        "line2": "",
        "city": "Glendale",
        "state": "California",
        "stateCode": "CA",
        "postalCode": "91203",
        "country": "United States",
        "countryCode": "US",
        "addressText": "Glendale, CA 91203, US"
      },
      "addressLocation": {
        "addressText": "82515 Shipleys Choice Circle, Apt. 1849E, Glendale, CA  91203",
        "country": "United States",
        "countryCode": "US",
        "state": "California",
        "stateCode": "CA",
        "zip": "91203",
        "city": "Glendale"
      },
      "encounterAddressLocation": {
        "addressText": "82515 Shipleys Choice Circle, Apt. 1849E, Glendale, CA  91203",
        "country": "United States",
        "countryCode": "US",
        "state": "California",
        "stateCode": "CA",
        "zip": "91203",
        "city": "Glendale"
      },
      "country": "1",
      "countryCode": "+1",
      "createDate": "0001-01-01T00:00:00Z",
      "dob": "3/03/1971",
      "gender": "M",
      "homePhone": "",
      "lastName": "Customer",
      "mobilePhone": "+14436188251",
      "patientName": "Karen",
      "personId": "bfde4ae8-bb97-459c-ad3f-afc888bd30bd",
      "mobilePhoneCountryCodeId": 1
    }
  ],
  "total": 1
}

Creating a Patient

For a patient to have a consultation on the VCM system, they must have an account on it. If you have confirmed that the patient isn't in our system, you can create an account for them with the following call.

To create a user, you will need to post a JSON request to /api/v2/admin/patients with the following parameters:

  • firstName - (string) The patient's first name
  • lastName - (string) The patient's last (family) name
  • email - (string) The e-mail address for the user. This will be their login
  • dob - (string) An ISO 8601 date representing the patient's date of birth
  • address - null - deprecated
  • addressObject - (object) The complete address of the patient
    • line1 - (string) Line 1 of the patient address
    • line2 - (string) Line 2 of the patient address
    • city - (string) City of the patient address
    • state & stateCode - (string) State code of the patient address, can be blank for non US addresses
    • country & countryCode - (string) ISO Country code of the patient address, view codes here
  • countryId - (integer) The ID of the country where the user resides. You can find a list of country IDs with the [Utility-Calls#getCountry](Get Country) API call
  • timeZoneId - (integer) The ID of the timezone for the user. You can find a list of timezones with the [Utility-Calls#getTz](Get Timezone) API call
  • mobileNumberWithCountryCode - (string) The user's mobile number (used for SMS appointment reminders)
  • gender - (character) Either M for male or F for female
  • preventSendingInvitation - (boolean) Optional. Set to "true" if you want to suppress the patient getting an account creation e-mail from the VCM system. Useful for account creation for SSO purposes. Defaults to "false".
  • status - (integer) Optional. Set to "1" if you want the user activated immediately. This makes the most sense if you set preventSendingInvitation to true. Defaults to "-1" which means the user account is not active.
  • createUserWithoutEmail - (bool) The user can be created without email. Set to true if you want to create user without email address (login).

You will get back a JSON response with a success message and the user's patient ID if the creation was a success.

Note that you must provide a bearer authentication token for a user that has permission to create users.

Example:

The following example shows the creation of a patient and a successful response.

Request

POST https://sandbox.connectedcare.md/api/v2/admin/patients

Headers Sent:

  • X-Developer-Id: ****
  • Authorization: Bearer ****
  • X-Api-Key: ****

Request Body: Response Code (Success): 200 OK

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "jdoe@example.com",
  "dob": "1981-12-10T10:01:01Z",
  "address": null,
  "addressObject": {
         "line1": "121 W Lexington Drive",
         "line2": "Suite 412",
         "city": "Glendale",
         "state": "CA",
         "stateCode": "CA",
         "postalCode": "91203",
         "countryCode": "US",
         "country": "US"
      },
  "countryId": 1,
  "timeZoneId": 83,
  "mobileNumberWithCountryCode": "+1-555-555-4321",
  "gender": "M"
}

Response

{
  "data": [
    {
      "patientId": 3338
    }
  ],
  "message": "Success"
}

Deactivating (Deleting) A Patient

If you need to remove a patient's access to the VCM system, it's very easy to deactivate their account. Note that you will not remove any data from the system, but rather just render their account inactive. This preserves data that may be required in the future and allows you to re-activate a user should it be needed.

To use this endpoint, make a delete request to v2/admin/patients/ID where ID is the patient ID for the user. You can find the patient ID by requesting the details for the patient's e-mail address.

If the call is successful, a 204 status code will be returned with no response body. If the ID passed does not exist in the system, a 404 will be returned.

Example:

The following example shows us deactivating a patient with the ID 3338.

Request

DELETE https://sandbox.connectedcare.md/api/v2/admin/patients/3338

Headers Sent:

  • X-Developer-Id: ****
  • Authorization: Bearer ****
  • X-Api-Key: ****

Response

Response Code (Success): 204 No Content

No content is returned from this call, just the status code.

Activate / Deactivate Patients

PUT v2/clinicians/patients can be used to update the status of patients.
The payload is a JSON of an array (data) of patient info:

  • patientId: int
  • userId: int (userId of the adult patient; if userId is not null, dependents will be activated / deactivated along with the adult patient)
  • status: int (1 activate, 0 deactivate)

Example:

The following example shows us activating a patient user patientId 1234, userId 1001 and deactivating a patient with the patientId 2345.

Request

PUT https://sandbox.connectedcare.md/api/v2/clinicians/patients

Headers Sent:

  • X-Developer-Id: ****
  • X-Api-Key: ****
  • Authorization: Bearer ****

Request Body:

{
  "data": [
    {
      "patientId": 1234,
      "userId": 1001,
      "status": 1
    },
    {
      "patientId": 2345,
      "status": 0
    }
  ]
}

Response

Response Code (Success): 204 No Content

No content is returned from this call, just the status code.

Cancel all patient's future appointments

If you need to cancel all patient's future appointments in the VCM system, instead of only one, you can use this endpoint. Note that the corresponding notifications will be sent to the involved persons.

To use this endpoint, make a delete request to v2/admin/patients/ID/appointments where ID is the patient ID for the user. You can find the patient ID by requesting the details for the patient's e-mail address.

If the call is successful, a 200 status code will be returned with no response body. If the ID passed does not exist in the system or doesn't belong to the caller's hospital, a 400 will be returned. This endpoint is intended for use only by hospital staff, if not, a 401 status code will be returned.

Example:

The following example shows us canceling all future appointments for the patient with ID 3338.

Request

DELETE https://sandbox.connectedcare.md/api/v2/admin/patients/3338/appointments

Headers Sent:

  • X-Developer-Id: ****
  • Authorization: Bearer ****
  • X-Api-Key: ****

Response

Response Code (Success): 200 OK

No content is returned from this call, just the status code.

Creating a Dependent Patient

You can create a dependent of given patientId with the following call.

To create a dependent patient, you will need to post a JSON request to /api/v2/admin/patient/{patientId}/dependent with the following parameters:

{
  "relationship": {
    "$id": "2",
    "relationCodeId": 1,
    "isAuthorized": "sample string 2"
  },
  "createUserWithoutEmail": true,
  "emailAddress": "sample string 2",
  "patientProfileData": {
    "$id": "3",
    "patientId": 1,
    "patientName": "sample string 2",
    "lastName": "sample string 3",
    "dob": "2019-09-10T17:56:50.8341994Z",
    "bloodType": 1,
    "eyeColor": 1,
    "gender": "sample string 4",
    "ethnicity": 1,
    "hairColor": 1,
    "homePhone": "sample string 5",
    "mobilePhone": "sample string 6",
    "schoolName": "sample string 7",
    "schoolContact": "sample string 8",
    "primaryPhysician": "sample string 9",
    "primaryPhysicianContact": "sample string 10",
    "physicianSpecialist": "sample string 11",
    "physicianSpecialistContact": "sample string 12",
    "preferedPharmacy": "sample string 13",
    "pharmacyContact": "sample string 14",
    "address": "sample string 15",
    "addressObject": {
      "$id": "4",
      "line1": "sample string 1",
      "line2": "sample string 2",
      "city": "sample string 3",
      "state": "sample string 4",
      "stateCode": "sample string 5",
      "postalCode": "sample string 6",
      "country": "sample string 7",
      "countryCode": "sample string 8",
      "addressText": "sample string 1, sample string 2, sample string 3, sample string 5 sample string 6, sample string 8"
    },
    "profileImagePath": "sample string 16",
    "height": "sample string 17",
    "weight": "sample string 18",
    "heightUnit": 1,
    "weightUnit": 1,
    "organization": "sample string 19",
    "location": "sample string 20",
    "organizationId": 1,
    "locationId": 1,
    "identifiers": [
      {
        "$id": "5",
        "identifierUsageCode": "none",
        "identifierUsageTitle": "sample string 1",
        "identifierTypeCode": "None",
        "identifierTypeTitle": "sample string 2",
        "namespace": "sample string 3",
        "value": "sample string 4",
        "effectiveDate": "2019-09-10T17:56:50.8505118Z",
        "expiredDate": "2019-09-10T17:56:50.8505118Z",
        "assignerOrg": "sample string 6",
        "statusCode": 0,
        "readOnly": true
      },
      {
        "$ref": "5"
      }
    ],
    "countryCode": "sample string 21",
    "mobilePhoneCountryCodeId": 1,
    "homePhoneCountryCodeId": 1
  },
  "patientMedicalHistoryData": {
    "$id": "6",
    "allergicMedication1": 1,
    "allergicMedication2": 1,
    "allergicMedication3": 1,
    "allergicMedication4": 1,
    "isChildBornFullTerm": "sample string 1",
    "isChildBornVaginally": "sample string 2",
    "isChildDischargeMother": "sample string 3",
    "isOneYearBelowChild": "sample string 4",
    "isVaccinationUpToDate": "sample string 5",
    "medicalCondition1": 1,
    "medicalCondition2": 1,
    "medicalCondition3": 1,
    "medicalCondition4": 1,
    "patientId": 6,
    "priorSurgery1": "sample string 7",
    "priorSurgery2": "sample string 8",
    "priorSurgery3": "sample string 9",
    "surgery1Month": 1,
    "surgery1Year": 1,
    "surgery2Month": 1,
    "surgery2Year": 1,
    "surgery3Month": 1,
    "surgery3Year": 1,
    "takingMedication1": 1,
    "takingMedication2": 1,
    "takingMedication3": 1,
    "takingMedication4": "sample string 10"
  },
  "medicationAllergies": [
    {
      "$id": "7",
      "asserterPersonId": "080efbd8-f030-4e40-8a83-eff21b3daca3",
      "asserterFullName": "sample string 1",
      "recorderPersonId": "e9ed877b-beac-41eb-8f51-efd18e917a52",
      "recorderFullName": "sample string 2",
      "assertedDate": "2019-09-10T17:56:50.8702963Z",
      "recordedDate": "2019-09-10T17:56:50.8702963Z",
      "onsetDate": "2019-09-10T17:56:50.8702963Z",
      "lastOccurrenceDate": "2019-09-10T17:56:50.8702963Z",
      "criticalityId": 0,
      "typeId": 0,
      "categoryId": 0,
      "code": 3,
      "description": "sample string 4",
      "notes": "sample string 5"
    },
    {
      "$ref": "7"
    }
  ],
  "timeZoneId": 87
}

Sample Request and Response

POST /api/v2/admin/patient/31730/Dependent HTTP/1.1
Host: api.qa1.snapvcm.com
Authorization: Bearer {{accesstoken}}
Content-Type: application/json; charset=UTF-8
X-Developer-Id: {{developerId}}
X-Api-Key: {{apikey}}
cache-control: no-cache
Postman-Token: aeeb6af5-9f6c-426e-8efa-36326e0ffafb
{
    "patientProfileData": {
        "patientName": "LAURIE Jr1",
        "lastName": "BOYER",
        "dob": "10/23/2000",
        "gender": "F",
        "homePhone": "+1701-223-6421",
        "mobilePhone": "+1701-226-4034",
        "addressObject": {
            "line1": "2201 Harbor Dr",
            "line2": null,
            "city": "Bismarck",
            "state": "North Dakota",
            "stateCode": "ND",
            "postalCode": "58504",
            "country": "US",
            "countryCode": "US"
        },
        "height": "5|5",
        "weight": "170",
        "heightUnit": 4623,
        "weightUnit": 4621
    },
    "patientMedicalHistoryData": {}
}------WebKitFormBoundary7MA4YWxkTrZu0gW--

response

{
    "data": [
        {
            "patientId": 31765,
            "securityToken": "",
            "patientName": "LAURIE Jr1",
            "lastName": "BOYER",
            "mobilePhone": "+1701-226-4034",
            "homePhone": "+1701-223-6421",
            "location": ""
        }
    ],
    "total": 1
}

Contents

Clone this wiki locally