User Onboarding

The process of adding a new user to the system is onboarding. There are two types of users in Carium: Providers and Patients. Each type of user can be onboarded in two ways: Manual and Self-Service.

In manual onboarding, a Provider explicitly enters the user's information into the system and Carium delivers email or SMS instructions for signing up. Manual onboarding is typically used when you know which patients you want to onboard ahead of time, and you already have their contact information.

In self-service onboarding, the user installs the Carium App and enters a organization-wide Organization Code, along with their personal information. Providers may edit the user's information after the user has signed up. Self-service onboarding is typically used to pre-provision groups before you know specifically which patients will be using the system.

Manual onboarding

When a Provider User manually onboards a new Patient, both an Individual and User record will be created for that Patient. The created Individual will also automatically be shared with that Provider's Organization.

A new Patient is onboarded by sending a POST to /patients/. There are a few different things to consider when onboarding a new Patient:

• Do you have the minimum information required to onboard this Patient (first/last name, date of birth, email, or phone number)?
• Do you want to invite this Patient to use the Patient app (either via the web or mobile apps)?
• What's the best way to interact with this Patient (email, SMS)?
• What's this Patient's preferred language (English and Spanish are currently supported)?

Request Body Attributes

The POST sent to /showboat/v1/patients/ follows JSON-API, and so must be wrapped in:

{
    "data": {
        "attributes": {},
        "type": "ui-patients"
    }
}

The most important data is on the attributes portion of the request body.

Attribute	Required?	Description	Example
birth-date	Yes	Patient's date of birth (YYYY-MM-DD format)	"1970-01-02"
email	Not if mobile-phone is given	Patient's email address	"john.doe@domain.com"
gender	No	Patient's gender (female | male | other | pnta | unknown)	"pnta"
first-name	Yes	Patient's first/given name	"John"
individual-group-id	No	UUID of an IndividualGroup that should include the new Patient	"1e5402d8-2374-4392-af92-dcf5f9672e31"
last-name	Yes	Patient's last/family name	"Doe"
locale	Yes	Patient's locale/language (en_US | es_US)	"en_US"
mobile-phone	Not if email is given	Patient's SMS-enabled mobile number	"+13215551234"
notifications	No	How to invite Patient to use Patient app (email | sms)	["email", "sms"]
preferred-name	No	Patient's preferred name	"Jack"
username	No	Patient's username used to access Patient app (must match email or mobile-phone)	"john.doe@domain.com"

How do the questions above map to the attributes passed to /patients/?

Here are a few examples of how to onboard different Patients while inviting them to use the Patient app. For these examples, leave out the common fields of birth-date, gender, first-name, last-name, individual-group-id, last-name, and preferred-name as they don't impact the Patient app invitations.

Patient app via email

Sending the following attributes will result in an email being sent to john.doe@domain.com with a link to allow the Patient to verify their email address and set a password. They can then use john.doe@domain.com as their username and that password to access the Patient app via Carium's web interface or one of Carium's mobile apps (available on iOS and Android).

{
    "email": "john.doe@domain.com",
    "mobile-phone": "+13215551234",
    "notifications": ["email"],
    "username": "john.doe@domain.com"
}

Patient app via SMS

Sending the following attributes will result in an SMS message being sent to +13215551234 with a link to allow the Patient to verify their phone number and set a password. They can then use +13215551234 as their username and that password to access the Patient app via Carium's web interface or one of Carium's mobile apps (available on iOS and Android).

{
    "email": "john.doe@domain.com",
    "mobile-phone": "+13215551234",
    "notifications": ["sms"],
    "username": "+13215551234"
}

Patient app via both email and SMS

Sending the following attributes will result in both an email being sent to john.doe@domain.com and an SMS message being sent to +13215551234. Both messages will include links to allow the Patient to verify with a link to allow the Patient to verify the email or phone number, respectively and set a password. Whichever invitation they choose to use to complete their registration will decide what their username will be.

If they use the link set to them via SMS, then their username will be +13215551234, if they use the link emailed to them, then their username will be john.doe@domain.com. They can then use that username and the password they entered to access the Patient app via Carium's web interface or one of Carium's mobile apps (available on iOS and Android).

{
    "email": "john.doe@domain.com",
    "mobile-phone": "+13215551234",
    "notifications": ["email", "sms"],
    "username": "+13215551234"
}

No Patient app with only email

Sending the following attributes will result in no invitations being sent to the Patient at all. The Patient won't have any access to the Patient app. Their username will be set to john.doe@domain.com initially, but they can later be sent an invitation via either SMS or email.

{
    "email": "john.doe@domain.com"
}

No Patient app with only phone

Sending the following attributes will result in no invitations being sent to the Patient at all. The Patient won't have any access to the Patient app. Their username will be set to +13215551234 initially, but they can later be sent an invitation via either SMS or email.

{
    "mobile-phone": "+13215551234"
}

No Patient app with both email and phone

Sending the following attributes will result in no invitations being sent to the Patient at all. The Patient won't have any access to the Patient app. Their username will be set to john.doe@domain.com initially, but they can later be sent an invitation via either SMS or email.

{
    "email": "john.doe@domain.com",
    "mobile-phone": "+13215551234"
}