Examples

This page contains a number of examples for interacting with the Carium API. The examples use the Python programming language and the requests library to make HTTP requests to the Carium API. These examples aren't intended to be exhaustive or to cover every aspect of the API options, but instead provide a representative example of common use cases.

If you have a recent version of Python installed, you can install the requests library using pip:

pip install requests

warning

The examples provided here are intended to be illustrative and aren't intended to be used in a production environment. They're by no means exhaustive and don't represent best practices for error handling, security, or performance. Instead they're written in the simplest manner possible to act as a starting point for developers who are new to the Carium API.

Running the Login example is required to obtain an access token that's used in the remaining examples.

POST /identity/v1/login/

To interact with the Carium API, you need first to obtain an access token. The access token is used to authenticate your requests to the API. The code shown below demonstrates how to obtain an access token by sending a POST request to the /identity/v1/login/ endpoint. The login function takes three arguments: username, password, and optionally an mfa_token. It returns the access token as a string that can be used in subsequent requests.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:

    url = 'https://api.carium.com/identity/v1/login/'
    headers = {
        'Content-Type': 'application/json',
        'Accept': 'application/vnd.api+json'
    }
    data = {
        'username': username,
        'password': password
    }

    if mfa_token:
        data['totp-code'] = mfa_token

    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()['access-token']

if __name__ == '__main__':
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}

Create a New Patient Record

POST /showboat/v1/patients/

Creating a patient is a complex process that involves multiple microservices in the Carium platform. To simplify the process the /showboat/v1/patients endpoint is provided to create a patient record in a single request. The table below describes the primary fields that are utilized when creating a new patient record.

Field	Description	Required?
`first-name`	The first name of the patient.	Yes
`last-name`	The last name of the patient.	Yes
`birth-date`	The birth date of the patient in the format `YYYY-MM-DD`.	Yes
`gender`	One of `male`, `female`, `pnta`, `other`, or `unknown`	Yes
`email`	The email address of the patient.	No, if mobile-phone is provided.
`mobile-phone`	The mobile phone number of the patient.	No, if email is provided.
`locale`	The locale of the patient, one of `en_US` or `es_US`	No, will default to `en_US`
`individual-group-ids`	A list of group IDs that the patient belongs to.	No
`username`	Must be equal to `email` or `mobile-phone` specified above	No, will default to email
`organization-id`	The ID of your organization.	Yes

The following code block can be merged with the login example to create a new patient record. If the record is created successfully the function will return the individual-id of the new patient. The individual-id which is a UUID and will be used across many of the following examples to identify the patient.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

patients_url = 'https://api.carium.com/showboat/v1/patients/'
patient_data = {
    "data": {
        "attributes": {
            "first-name": "James",
            "last-name": "Reece",
            "birth-date": "1980-07-04",
            "gender": "male",
            "email": "james.reece@example.com",
            "mobile-phone": "+15551234567",
            "locale": "en_US",
            "individual-group-ids": ["aa6243fb-e4c1-44a0-ae3c-f4c4ab115002", "2097e072-92f6-4333-99d6-9693d63be652"],
            "username": "james.reece@example.com",
            "organization-id": "8d25a2a6-8219-40d1-a34f-c24ec69f4f72"
        },
        "type": "ui-patients"
    }
}

def create_patient(payload: dict) -> str:
    response = requests.post(patients_url, headers=headers, json=patient_data)
    response.raise_for_status()
    return response.json()['data']['id']

if __name__ == '__main__':
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}, "Accept": "application/vnd.api+json"}
    individual_id = create_patient(patient_data)

Create a Patient Invitation

POST /identity/v1/resend-invitation/

The previous example created a patient record, but the patient hasn't yet been invited to the Carium platform. This example shows how to invite a patient to use the Carium web or mobile applications to interact with the platform. The invitation will be sent to the email address or mobile phone number provided in the patient record.

In this case, we only need to specify the username and the notifications fields. The username should be the same as the username set while creating the patient record. The notifications field is a list of the types of notifications that the patient should receive. Notifications can be sms or email. While the API supports sending both simultaneously typically only one invitation type is sent.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

invitation_url = 'https://api.carium.com/identity/v1/resend-invitation/'
invitation_data = {
    "data": {
        "attributes": {
            "username": "example@example.com",
            "notifications": ["email"]
        }
    }
}

def send_invitation(payload: dict) -> None:
    response = requests.post(invitation_url, headers=headers, json=invitation_data)
    response.raise_for_status()

if __name__ == '__main__':
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}
    send_invitation(invitation_data)

Appointments

Create an Appointment

POST /caredb/v1/org-appointments/

The following table describes the primary fields that are utilized when creating a new appointment.

Field	Description	Required?
organization-id	The ID of your organization.	Yes
individual-id	The `individual-id` of the patient.	Yes
practitioner-id	The ID of the practitioner from `/caredb/v1/org-practioners/`	Yes
start-time	The start time of the appointment in the format `YYYY-MM-DDTHH:MM:SSZ`.	Yes
end-time	The end time of the appointment in the format `YYYY-MM-DDTHH:MM:SSZ`.	Yes
status-id	The `id` of the corresponding status from `/caredb/v1/org-appointment-statuses/`	Yes
type-id	The `id` of the corresponding type from `/caredb/v1/org-appointment-types/`	Yes
add-video-channel	A boolean indicating if a Carium video channel should be attached to the appointment.	Yes
guest-url	The URL that the guest should use to join the video call. (When no Carium video channel is utilized)	No
host-url	The URL that the host should use to join the video call. (When no Carium video channel is utilized)	No
description	A description of the appointment.	No
patient-instruction	Instructions for the patient. (This is often used to store a rescheduling link)	No
location	A string that describes the location of the appointment.	No

The following code block can be merged with the login example to create a new appointment. If the appointment is successfully created the function will return the id of the new appointment.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

appointments_url = 'https://api.carium.com/caredb/v1/org-appointments/'
appointment_data = {
    "data": {
        "attributes": {
            "organization-id": "8d25a2a6-8219-40d1-a34f-c24ec69f4f72",
            "individual-id": "aa6243fb-e4c1-44a0-ae3c-f4c4ab115002",
            "practitioner-id": "2097e072-92f6-4333-99d6-9693d63be652",
            "start-time": "2022-01-01T09:00:00Z",
            "end-time": "2022-01-01T09:30:00Z",
            "status-id": "8d25a2a6-8219-40d1-a34f-c24ec69f4f72",
            "type-id": "aa6243fb-e4c1-44a0-ae3c-f4c4ab115002",
            "add-video-channel": False,
            "guest-url": "https://example.com/guest",
            "host-url": "https://example.com/host",
            "description": "This is a test appointment",
            "patient-instruction": "Please reschedule at https://example.com/reschedule",
            "location": "Virtual"
        },
        "type": "org-appointments"
    }
}

def create_appointment(payload: dict) -> str:
    response = requests.post(appointments_url, headers=headers, json=appointment_data)
    response.raise_for_status()
    return response.json()['data']['id']

if __name__ == '__main__':
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}
    appointment_id = create_appointment(appointment_data)

Get a Single Appointment

GET /caredb/v1/org-appointments/{id}

The following code allows you to retrieve a single appointment by its id. This is the same id generated by the create_appointment function above.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

appointments_url = 'https://api.carium.com/caredb/v1/org-appointments/'
appointment_id = 'aa6243fb-e4c1-44a0-ae3c-f4c4ab115002'

def get_appointment(appointment_id: str) -> dict:
    response = requests.get(f"{appointments_url}/{appointment_id}/", headers=headers)
    response.raise_for_status()
    return response.json()

if __name__ == '__main__':
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}
    appointment = get_appointment(appointment_id)

Update an Appointment

PATCH /caredb/v1/org-appointments/{id}

The following code allows you to update an appointment by its id. This is the same id generated by the create_appointment function above. This example will illustrate how to update the time that the appointment occurs.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

appointment_id = "aa6243fb-e4c1-44a0-ae3c-f4c4ab115002"
appointments_url = f"https://api.carium.com/caredb/v1/org-appointments/{id}/"
appointment_data = {
    "data": {
        "attributes": {
            "start-time": "2022-01-01T10:00:00Z",
            "end-time": "2022-01-01T10:30:00Z"
        },
        "type": "org-appointments"
    }
}

def update_appointment(appointment_id: str, payload: dict) -> dict:
    response = requests.patch(f"{appointments_url}/{appointment_id}/", headers=headers, json=appointment_data)
    response.raise_for_status()
    return response.json()

if __name__ == '__main__':
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}
    updated_appointment = update_appointment(appointment_id, appointment_data)

Delete an Appointment

DELETE /caredb/v1/org-appointments/{id}

Deleting an appointment is a simple process that only requires the id of the appointment. The following code block illustrates the process.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

appointment_id = "aa6243fb-e4c1-44a0-ae3c-f4c4ab115002"
appointments_url = f"https://api.carium.com/caredb/v1/org-appointments/{id}/"

def delete_appointment(appointment_id: str) -> None:
    response = requests.delete(f"{appointments_url}/{appointment_id}/", headers=headers)
    response.raise_for_status()

if __name__ == '__main__':
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}
    delete_appointment(appointment_id)

Organization Documents (Attachments)

Documents can be attached to patient records using the org-documents endpoints. Each document will be displayed in the patient record under the "Attachments" tab. Each document must be assigned a class. Available classes can be managed using the org-document-classes endpoint.

List document classes

GET /caredb/v1/org-document-classes/

The following code will list the document-classes currently available on the system. The id of the document-class will later be used when creating or searching for particular documents.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

org_document_class_url = 'https://api.carium.com/caredb/v1/org-document-classes/'
organization_id = "8d25a2a6-8219-40d1-a34f-c24ec69f4f72"


def list_classes() -> dict:
    params = {"organization-id": organization_id}
    response = requests.get(f"{org_document_class_url}/", headers=headers, params=params)
    response.raise_for_status()
    return response.json()

if __name__ == '__main__':
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}
    appointment = get_appointment(appointment_id)

Upload a Document

POST /caredb/v1/org-document-references/

POST /caredb/v1/org-document-references/{id}/process-upload/

Uploading a new document is a multi-step process.

Create the new org-document-reference record.
Retrieve the upload-url from the response.
Upload the document to the upload-url.
Call the process-upload endpoint to finalize the upload.

The following code block demonstrates how to upload a document to the Carium platform.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

org_documents_url = 'https://api.carium.com/caredb/v1/org-document-references/'

document_data = {
    "data": {
        "attributes": {
            "attachment-content-type": "application/pdf",
            "attachment-filename": "example.pdf",
            "class-id": "aa6243fb-e4c1-44a0-ae3c-f4c4ab115002",
            "name": "Example Document",
            "description": "This is an example document",
            "individual-id": "aa6243fb-e4c1-44a0-ae3c-f4c4ab115002",  # This is the patient's individual-id
            "organization-id": "8d25a2a6-8219-40d1-a34f-c24ec69f4f72"
        },
        "type": "org-document-references"
    }
}

def create_document(payload: dict) -> tuple:
    response = requests.post(org_documents_url, headers=headers, json=document_data)
    response.raise_for_status()
    doc_id = response.json()["data"]["id"]
    upload_url = response.json()["data"]["attributes"]["upload-info"]["upload-url"]
    upload_data = response.json()["data"]["attributes"]["upload-info"]["upload-data"]
    return (doc_id, upload_url, upload_data)

def upload_document(doc_id: str, upload_url: str, upload_data: dict, file_name: str, file_path: str) -> None:
    with open(file_path, "rb") as file_obj:
        # Note:  This post does not require the use of the authorization header
        response = requests.post(upload_url, data=upload_data, files={'file': (file_name, file_obj)})
        response.raise_for_status()
    process_upload_url = f"{org_documents_url}{doc_id}/process-upload/"
    response = requests.post(process_upload_url, headers=headers)
    response.raise_for_status()
    return

if __name__ == "__main__":
    access_token = login("username", "password")
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}
    doc_id, upload_url, upload_data = create_document(document_data)
    upload_document(doc_id, upload_url, upload_data, 'example.pdf', '/path/to/example.pdf')

List Documents

GET /caredb/v1/org-document-references/

The following code block will list all documents that are currently attached to a patient record. Other filters are available as needed, see the full API documentation for more details.

import requests

def login(username: str, password: str, mfa_token: str=None) -> str:
    # login code here

org_documents_url = "https://api.carium.com/caredb/v1/org-document-references/"

individual_id = "aa6243fb-e4c1-44a0-ae3c-f4c4ab115002" # This is the patient we wish to retrieve documents for
organization_id = "8d25a2a6-8219-40d1-a34f-c24ec69f4f72"

def list_documents(individual_id: str, organization_id: str) -> dict:
    params = {"filter[individual-id]": individual_id, "organization-id": organization_id}
    response = requests.get(org_documents_url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    access_token = login('username', 'password')
    headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/vnd.api+json"}
    documents = list_documents(individual_id, organization_id)
    print(documents)

Download a Document

GET /caredb/v1/org-document-references/{id}/get-download-info/

To download a document, you only need to have the id of the org-document-reference record. A GET request to the URL /v1/org-document-references/{id}/get-download-info/ will return another URL which will allow you to download the document with a simple GET request to that URL.

Login​

Create a New Patient Record​

Create a Patient Invitation​

Appointments​

Create an Appointment​

Get a Single Appointment​

Update an Appointment​

Delete an Appointment​

Organization Documents (Attachments)​

List document classes​

Upload a Document​

List Documents​

Download a Document​

Login