Authentication ¶

Orange API uses access token authentication, like many REST services and similar to (and in fact a semi-compatible subset of) OAuth2. First you use stored user credentials (see POST /auth/token below) to generate an access token, and then pass this access token into the Authorization header of all other requests. All requests apart from user registration and token generation need this authentication.

Precisely, the access token should be sent in the Authorization header in the form

Authorization: Bearer ACCESS_TOKEN

and should be sent in plaintext, not base64 encoded.

{
    email: "foo@bar.com",
    password: "foobar"
}

{
    access_token: "abcdefgh123456789",
    success: true
}

Users ¶

{
    email: "foo@bar.com",
    password: "foobar",
    first_name: "Foo",
    last_name: "Bar",
    phone: "6177140000",
    role: "clinician"
}

{
    email: "foo@bar.com",
    first_name: "Foo",
    last_name: "Bar",
    phone: "6177140000",
    role: "clinician",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    email: "foo@bar.com",
    first_name: "Foo",
    last_name: "Bar",
    phone: "6177140000",
    role: "clinician",
    npi: "1245319599",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    first_name: "Foo",
    last_name: "Baz",
    phone: "6177140001",
    npi: "1245319599",
    password: "foobaz"
}

{
    email: "foo@bar.com",
    first_name: "Foo",
    last_name: "Baz",
    phone: "6177140001",
    role: "clinician",
    npi: "1245319599",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    email: "foo@bar.com",
    first_name: "Foo",
    last_name: "Bar",
    phone: "6177140000",
    role: "clinician",
    npi: "1245319599",
    success: true
}

{
    email: "foo@bar.com"
}

{
    email: "foo@bar.com",
    success: true
}

Requests ¶

Each user can request access to another user’s patients. This is done by making a POST request to /requested, after which the request can be viewed at GET /requested and cancelled at DELETE /requested/:id if needed.

The user to which the request was made can then view the request at /requests and close it by making a DELETE request to /requests/:id. As discussed in greater detail below, this DELETE request should contain a JSON body with either status: accepted or status: rejected depending on the outcome. Note that DELETEing the request does not actually share any patients: that must be done seperately using the POST /patients/:patientid/shares endpoint. This way the user can choose to selectively share just some of their patients.

Deleted requests are still shown, so the status field should be used to determine between requests. Possible values are pending, cancelled, accepted and rejected.

Note that if user A requests access from user B, the request ID for user A (at /requested) is not necessarily the same as the request ID for user B (at /requests).

Authorization: Bearer ACCESS_TOKEN

{
    email: "another@user.com"
}

{
    id: 1,
    email: "another@user.com",
    status: "pending",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    requests: [
        {
            id: 1,
            email: "another@user.com"
            status: "pending",
        },
        ...
    ],
    count: 2,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    email: "another@user.com",
    status: "cancelled",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    requests: [
        {
            id: 1,
            email: "original@user.com",
            status: "pending"
        },
        ...
    ],
    count: 2,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    status: "accepted"
}

{
    id: 1,
    email: "another@user.com",
    status: "accepted",
    success: true
}

Patients ¶

Remember, patients are the resources for which we actually store medication/etc data, rather than users (and we have a many to many association between patients and users).

When a user is created, a corresponding patient for them is also created. The user can then optionally create more patients for e.g., children dependents.

Patients can then be shared with other users. There are three levels of sharing: family prime (prime), family (family) and anyone (anyone). Family prime is intended to represent family extremely close to the patient (e.g., parents) who should have access to almost everything, family is intended for wider family of the patient, and anyone is intended for everyone else (e.g., doctors).

At the patient level, a user’s access to data is determined by which one of the above three groups they’re a member of. API requests can be made to set global read (read) or read-write (write) permissions for each of the three share groups for each patient, as well as an overriding read/write permission for each user the patient is shared with (so each share has either read, write or default permissions, where default means to just use the patient-wide permissions for the relevant share group). However, note that these permissions are all set to sensible defaults: specifically all three share groups have write access by default, and all users created have default share permissions. Note that this does not grant every user a patient is shared with full read-write access to their data, because medications have a slightly more complex permissions structure (described below).

In a patient response object, access_anyone, access_family and access_prime represent the permissions of the anyone/family/family prime share user groups respectively. The access field denotes the current user’s access to the patient, and will always be either read or write (if it is set to default, it will be changed to the relevant value; this is not true of the /patients/:id/share/ endpoints).

These generic permissions control access to most of a patient’s resources, but medications, journal entries, doses and schedules are slightly more complicated. As described in the medications section, each medication has its own additional set of access controls. For each of their medications, the patient can explicitly set the access level of family prime, family and anyone. This then controls access to that medication, any journal entries tagged with that medication, any schedule events for that medication, and any dose events for that medication.

There are four access levels that can be set for each group on this per-medication basis: read, write, none and default. read and write behave as they do in a patient-wide context, and none means that that user group has no access at all to the medication or it’s resources. default is slightly more complicated: rather than just delegating straight to the patient-level permissions, it has a slightly different meaning depending on the share group and medication details:

• For an anyone share, default gives the user read-only access

• For a family share on an as-needed medication (including medications that are both regular and as-needed), default gives the user write access.

• For a family share on a medication that is not as-needed (so is regular-only), default gives the user read-only access.

• For a prime share, default delegates to the patient-level permissions: it first looks at any explicit permissions specified in the share itself, and if that’s set to default then it looks as access_prime in the patient data.

There is one exception to this rule. The user who creates a medication is recorded as the creator of that medication, and they always have write access to that medication (even if, for example, the patient is shared with the user through the anyone group and the medication has access_anyone="default" (which would usually give them read-only access), that user will still have write access).

Each patient returned by the API has an avatar field containing the path of that patient’s avatar (image) endpoint. As documented below, GETting this path returns the user’s avatar (initially a default image) and POSTing to this path with raw image data sets the avatar to the POSTed data.

Each patient returned also has a creator field (which cannot be modified) containing the email address of the user who created the patient, and a me boolean field representing whether the patient corresponds to that user’s “own log”. me is true for the patient automatically created when a user registers, and false otherwise.

Authorization: Bearer ACCESS_TOKEN

{
    first_name: "Dependent",
    last_name: "Patient",
    birthdate: "1990-01-01",
    sex: "male",
    phone: "6177140000",
    access_anyone: "read",
    access_family: "read",
    access_prime: "write"
}

{
    id: 1,
    first_name: "Dependent",
    last_name: "Patient",
    birthdate: "1990-01-01",
    sex: "male",
    phone: "6177140000",
    avatar: "/v1/patients/1/avatar.jpg",
    creator: "foo@bar.com",
    me: true,
    access_anyone: "read",
    access_family: "read",
    access_prime: "write",
    access: "write",
    group: "owner",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    patients: [
        {
            id: 1,
            first_name: "Dependent",
            last_name: "Patient",
            birthdate: "1990-01-01",
            sex: "male",
            phone: "6177140000",
            avatar: "/v1/patients/1/avatar.jpg",
            creator: "foo@bar.com",
            me: true,
            access_anyone: "read",
            access_family: "read",
            access_prime: "write",
            access: "write",
            group: "owner"
        },
        ...
    ],
    count: 2,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    first_name: "Dependent",
    last_name: "Patient",
    birthdate: "1990-01-01",
    sex: "male",
    phone: "6177140000",
    avatar: "/v1/patients/1/avatar.jpg",
    creator: "foo@bar.com",
    me: true,
    access_anyone: "read",
    access_family: "read",
    access_prime: "write",
    access: "write",
    group: "prime",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    first_name: "Gin",
    last_name: "Smith",
    birthdate: "1991-01-01",
    sex: "female",
    phone: "6177140001",
    access: "write",
    group: "family",
    access_anyone: "read",
    access_family: "read",
    access_prime: "read"
}

{
    id: 1,
    first_name: "Gin",
    last_name: "Smith",
    birthdate: "1991-01-01",
    sex: "female",
    phone: "6177140001",
    avatar: "/v1/patients/1/avatar.jpg",
    creator: "foo@bar.com",
    me: true,
    access_anyone: "read",
    access_family: "read",
    access_prime: "read",
    access: "write",
    group: "family",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    first_name: "Gin",
    last_name: "Smith",
    birthdate: "1991-01-01",
    sex: "female",
    phone: "6177140001",
    avatar: "/v1/patients/1/avatar.jpg",
    creator: "foo@bar.com",
    me: true,
    access_anyone: "read",
    access_family: "read",
    access_prime: "write",
    access: "write",
    group: "owner",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

raw PDF data

Authorization: Bearer ACCESS_TOKEN

{
    id: 34,
    first_name: "Patient 11",
    last_name: "number 11",
    birthdate: "1990-01-01",
    sex: "male",
    phone: "6177140000",
    avatar: "/v1/patients/34/avatar.png",
    creator: "foo@bar.com",
    me: true,
    access_anyone: "read",
    access_family: "read",
    access_prime: "write",
    group: "anyone",
    access: "read",
    habits: {
        wake: null,
        sleep: null,
        breakfast: null,
        lunch: null,
        dinner: null,
        tz: "Etc/UTC"
    },
    entries: [
        {
            date: "2015-07-15T13:18:21.000-04:00",
            text: "example journal entry",
            medication_ids: [
                1
            ],
            mood: "",
            id: 1
        }
    ],
    doctors: [
        {
            name: "test doctor",
            phone: "",
            address: "",
            notes: "",
            id: 1
        }
    ],
    pharmacies: [
        {
            name: "test pharmacy",
            phone: "",
            address: "",
            hours: {
                monday: {},
                tuesday: {},
                wednesday: {},
                thursday: {},
                friday: {},
                saturday: {},
                sunday: {}
            },
            notes: "",
            id: 1
        }
    ],
    medications: [
        {
            name: "test medication",
            rx_norm: "",
            rx_number: "",
            ndc: "",
            dose: {
                quantity: 1,
                unit: "dose"
            },
            route: "",
            form: "",
            quantity: 1,
            type: "",
            fill_date: null,
            doctor_id: null,
            pharmacy_id: null,
            access_anyone: "default",
            access_family: "default",
            access_prime: "default",
            number_left: null,
            schedule: {
                as_needed: true,
                regularly: false
            },
            id: 1
        }
    ],
    doses: [
        {
            medication_id: 1,
            date: "2015-07-15T13:18:21.000-04:00",
            notes: "",
            id: 1
        }
    ],
    shares: [
        {
            is_user: true,
            access: "write",
            group: "owner",
            email: "foo26@bar.com",
            id: 42
        },
        {
            is_user: true,
            access: "default",
            group: "anyone",
            email: "foo25@bar.com",
            id: 43
        }
    ],
    success: true
}

Authorization: Bearer ACCESS_TOKEN

raw image data

Authorization: Bearer ACCESS_TOKEN

raw image data

{
    success: true,
    avatar: "/v1/patients/1/avatar.gif"
}

Authorization: Bearer ACCESS_TOKEN

{
    email: "care@giver.com",
    access: "read",
    group: "family"
}

{
    id: 1,
    email: "care@giver.com",
    access: "read",
    group: "family",
    is_user: true,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    shares: [
        {
            id: 1,
            email: "care@giver.com",
            access: "write",
            group: "family",
            is_user: true
        },
        ...
    ],
    count: 2,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    access: "write",
    group: "family"
}

{
    id: 1,
    email: "care@giver.com",
    access: "write",
    group: "family",
    is_user: true,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    email: "care@giver.com",
    access: "write",
    group: "family",
    is_user: true,
    success: true
}

Habits ¶

Authorization: Bearer ACCESS_TOKEN

{
    wake: "07:00 am",
    sleep: "11:00 pm",
    breakfast: "08:00 am",
    lunch: "12:00 pm",
    dinner: "07:00 pm",
    tz: "Etc/UTC",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    wake: "06:00 am",
    sleep: "10:00 pm",
    breakfast: "07:00 am",
    lunch: "11:00 am",
    tz: "London/Europe",
    dinner: "06:00 pm"
}

{
    wake: "06:00 am",
    sleep: "10:00 pm",
    breakfast: "07:00 am",
    lunch: "11:00 am",
    dinner: "06:00 pm",
    tz: "London/Europe",
    success: true
}

Journal Entries ¶

Basic free-text journal for the patient to enter notes about their day and such in. While medications can be tagged in journal entries, entries that correspond exactly to dose events should probably just be stored in the notes field of a dose event.

Hashtags are parsed from each journal entry and returned in a hashtags array of strings.

Authorization: Bearer ACCESS_TOKEN

{
    date: "2015-05-31T19:27:09+00:00",
    text: "Had an amazing day today, perhaps thanks in part to taking one more #Adderall than I was meant to this morning!! I #love you #Orange guys soooo much it's insane, but I should probably #go now to avoid #typing #too #much #hashtags #omgilovehashtags #Adderall",
    medication_ids: [1,4],
    mood: "Happy",
    hashtags: ["Adderall", "love", "Orange", "go", "typing", "too", "much", "hashtags", "omgilovehashtags"],
    success: true
}

{
    id: 1,
    date: "2015-05-31T19:27:09+00:00",
    text: "Had an amazing day today, perhaps thanks in part to taking one more #Adderall than I was meant to this morning!! I #love you #Orange guys soooo much it's insane, but I should probably #go now to avoid #typing #too #much #hashtags #omgilovehashtags #Adderall",
    medication_ids: [1,4],
    mood: "Happy",
    hashtags: ["Adderall", "love", "Orange", "go", "typing", "too", "much", "hashtags", "omgilovehashtags"],
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    entries: [
        {
            id: 1,
            date: "2015-05-31T19:27:09+00:00",
            text: "Had an amazing day today, perhaps thanks in part to taking one more Adderall than I was meant to this morning!! I #love you #Orange guys soooo much it's insane, but I should probably #go now to avoid #typing #too #much #hashtags #omgilovehashtags #Adderall",
            mood: "Happy",
            hashtags: ["Adderall", "love", "Orange", "go", "typing", "too", "much", "hashtags", "omgilovehashtags"],
            medication_ids: [1,4]
        },
        ...
    ],
    count: 46,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    date: "2015-05-31T19:27:09+00:00",
    text: "Had an amazing day today, perhaps thanks in part to taking one more Adderall than I was meant to this morning!! I #love you #Orange guys soooo much it's insane, but I should probably #go now to avoid #typing #too #much #hashtags #omgilovehashtags #Adderall",
    mood: "Happy",
    hashtags: ["Adderall", "love", "Orange", "go", "typing", "too", "much", "hashtags", "omgilovehashtags"],
    medications: [
        {
            id: 1,
            name: "Loratadine",
            rx_norm: "324026",
            pharmacy_id: 1
        },
        {
            id: 4,
            name: "Adderall",
            rx_norm: "123456789",
            pharmacy_id: 7
        }
    ],
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    date: "2015-05-31T19:27:09+00:00",
    text: "Had an absolute amazeballs day today, omg I love Adderall so much it's the greatest thing ever.",
    mood: "amazeballs",
    medication_ids: [2,3,8,9,10]
}

{
    id: 1,
    date: "2015-05-31T19:27:09+00:00",
    text: "Had an absolute amazeballs day today, omg I love Adderall so much it's the greatest thing ever.",
    mood: "amazeballs",
    hashtags: [],
    medication_ids: [2,3,8,9,10]
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    date: "2015-05-31T19:27:09+00:00",
    text: "Had an absolute amazeballs day today, omg I love Adderall so much it's the greatest thing ever.",
    mood: "amazeballs",
    hashtags: [],
    medication_ids: [2,3,8,9,10]
    success: true
}

Doctors ¶

Basic contact details for all of the doctors who’ve prescribed medication to a specified patient.

Authorization: Bearer ACCESS_TOKEN

{
    name: "Dr. X",
    phone: "(617) 617-6177",
    address: "Doctor Street, DC, 20052",
    notes: "Love this doc!",
    title: "Primary Care Physician"
}

{
    id: 1,
    name: "Dr. X",
    phone: "(617) 617-6177",
    address: "Doctor Street, DC, 20052"
    notes: "Love this doc!",
    title: "Primary Care Physician"
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    doctors: [
        {
            id: 1,
            name: "Dr. X",
            phone: "(617) 617-6177",
            address: "Doctor Street, DC, 20052",
            title: "Primary Care Physician",
            notes: "Love this doc!"
        },
        ...
    ],
    count: 3,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    name: "Dr. X",
    phone: "(617) 617-6177",
    address: "Doctor Street, DC, 20052",
    notes: "Love this doc!",
    title: "Primary Care Physician",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    name: "Dr. Y",
    phone: "(716) 716-7166",
    address: "Doctor Street, DC, 20052",
    title: "Primary Care Physician",
    notes: "Love this doc the most!"
}

{
    id: 1,
    name: "Dr. Y",
    phone: "(716) 716-7166",
    address: "Doctor Street, DC, 20052",
    title: "Primary Care Physician",
    notes: "Love this doc the most!",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    name: "Dr. X",
    phone: "(617) 617-6177",
    address: "Doctor Street, DC, 20052",
    notes: "Love this doc the most!",
    title: "Primary Care Physician",
    success: true
}

Pharmacies ¶

Details for all pharmacies from whom the selected patient receives medication.

The address field is geocoded into the lat and lon fields.

Authorization: Bearer ACCESS_TOKEN

{
    name: "Pharmacy X",
    address: "Pharmacy Street, DC, 20052"
    phone: "(617) 617-6177",
    hours: {
        monday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        tuesday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        wednesday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        thursday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        friday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        saturday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        sunday: {
            open: "09:00 am",
            close: "05:00 pm"
        }
    },
    notes: "Great pharmacy! Love the smell"
}

{
    id: 1,
    name: "Pharmacy X",
    address: "Pharmacy Street, DC, 20052"
    phone: "(617) 617-6177",
    hours: {
        monday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        tuesday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        wednesday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        thursday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        friday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        saturday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        sunday: {
            open: "09:00 am",
            close: "05:00 pm"
        }
    },
    lat: 50.9692224,
    lon: 0.0893951,
    notes: "Great pharmacy! Love the smell",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    pharmacies: [
        {
            id: 1,
            name: "Pharmacy X",
            ...
        },
        ...
    ],
    count: 3,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    name: "Pharmacy X",
    address: "Pharmacy Street, DC, 20052"
    phone: "(617) 617-6177",
    hours: {
        monday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        tuesday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        wednesday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        thursday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        friday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        saturday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        sunday: {
            open: "09:00 am",
            close: "05:00 pm"
        }
    },
    notes: "Great pharmacy! Love the smell",
    lat: 50.9692224,
    lon: 0.0893951,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    name: "Pharmacy. Y",
    phone: "(716) 716-7166",
    address: "Pharmacy Street, DC, 20052",
    hours: {
        tuesday: {
            open: "10:00 am"
        }
    },
    notes: "Doesn't smell like it used to"
}

{
    id: 1,
    name: "Pharmacy Y",
    address: "Pharmacy Street, DC, 20052"
    phone: "(716) 716-7166",
    hours: {
        monday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        tuesday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        wednesday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        thursday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        friday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        saturday: {
            open: "09:00 am",
            close: "05:00 pm"
        },
        sunday: {
            open: "09:00 am",
            close: "05:00 pm"
        }
    },
    notes: "Doesn't smell like it used to",
    lat: 50.9692224,
    lon: 0.0893951,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    name: "Pharmacy X",
    ...,
    success: true
}

Medications ¶

Data on regular medications a patient takes (either manually entered or retrieved via OAuth2 + FHIR from e.g., the DRE).

Medication data responses contain the number_left integer key: this is an estimation of the number of pills left based on fill_date and dose events submitted to the API. It will only be non-null if fill_date is non-null.

Permissions ¶

Medications have custom permissions that are used instead of the patient-wide permissions. Each medication has access_anyone, access_family and access_prime fields, each of which can be set to read, write, default or none to control the access the relevant share group (anyone, family or prime) has to the medication.

read, write and none are self-explanatory, but default is slightly more complex:

• For an anyone share, default gives the user read-only access

• For a family share on an as-needed medication (including medications that are both regular and as-needed), default gives the user write access.

• For a family share on a medication that is not as-needed (so is regular-only), default gives the user read-only access.

• For a prime share, default delegates to the patient-level permissions: it first looks at any explicit permissions specified in the share itself, and if that’s set to default then it looks as access_prime in the patient data.

There is one exception to this rule. The user who creates a medication is recorded as the creator of that medication, and they always have write access to that medication (even if, for example, the patient is shared with the user through the anyone group and the medication has access_anyone="default" (which would usually give them read-only access), that user will still have write access).

All three keys (access_anyone, access_family and access_prime) default to default, the recommended permission structure.

Schedule ¶

Various endpoints below take and output schedule data items, representing a regular schedule the patient should take a certain medication on. These are used to schedule reminders, and so are vitally important for the core of the app. The data format schedules must be in is precisely defined below, and must be followed exactly.

At it’s core, each schedule is an object.

It must contain the as_needed boolean key signifying whether the medication can be taken whenever needed (irregularly), and the regularly key signifying it should be taken on a regular schedule. At least one must be true. If regularly is false, no extra information is needed. If regularly is true, all of the following scheduling data is also required.

The schedule must have an until key signifying when the patient should stop taking the medication:

• In Perpetuity (forever)

until: {
    type: "forever"
}

• A certain number of times before stopping

until: {
    type: "number",
    stop: 5
}

• Until a certain date

until: {
    type: "date",
    stop: "2015-05-07"
}

The schedule must have a frequency key signifying on which days the patient should take the medication. Specific times of each day can be set using the times key, which is described below. frequency is an object consisting of an n key and a unit key: n is a number representing that the medication should be taken every n units, and unit specifies that unit (it can be "day", "month" or "year" only).

frequency can also have an optional exclude key, denoting that the medication should sometimes be skipped. If present, exclude must be an object consisting of exclude and repeat keys. exclude is an array of numbers representing the indices of days that must be swapped (where the first day it should be taken on has index 0, the second day it should be taken on has index 1, etc). repeat is a number representing the length of the exclude cycle: in other words, indices are taken modulo this. See the examples below for illustration.

• Daily

frequency: {
    n: 1,
    unit: "day"
}

• Weekdays only

frequency: {
    n: 1,
    unit: "day",
    exclude: {
        exclude: [5, 6],
        repeat: 7
    }
}

• Weekly

frequency: {
    n: 7,
    unit: "day"
}

• Every 28 days

frequency: {
    n: 28,
    unit: "day"
}

• Monthly

frequency: {
    n: 1,
    unit: "month"
}

• Quarterly

frequency: {
    n: 3,
    unit: "month"
}

• Quarterly apart from last quarter

frequency: {
    n: 3,
    unit: "month",
    exclude: {
        exclude: [3],
        repeat: 4
    }
}

frequency can also include a start key: a YYYY-MM-DD formatted (local) date representing any date that the medication was taken on (for example, the date the medication was started on). This means that, for example, Orange knows which day of the week a weekly medication is taken on. start can either be a string or an array of strings.

For example, a start array can be used to represent a medication that should be taken on the 1st and the 15th of every month

frequency: {
    n: 1,
    unit: "month",
    start: [
        "2015-01-01",
        "2015-01-15"
    ]
}

The schedule must also include a times key representing the times of the day the medication is taken on (i.e., frequency dictates which days and times dictates which times on those days). The number of times the medication is taken each day should not be explicitly specified, this is instead calculated from the length of times. times should be an array consisting of objects, each representing a time of the day at which the medication should be taken. There are 3 different types:

• Any time of the day

{
    type: "unspecified"
}

• An exact time (time should be formatted HH:MM a in local time)

{
    type: "exact",
    time: "09:00 am"
}

• A time based on the user’s habits. event can be either "breakfast", "lunch", "dinner" or "sleep". when can be either "before" or "after".

{
    type: "event",
    event: "lunch",
    when: "before"
}

When sent to the API, each time will be given an ID that will be returned in all endpoints returning the medication schedule. These IDs can be used in the /medications/:medicationid/times/:timeid endpoint to set notification settings on a user-specific basis for that specific time in that specific medication schedule.

The schedule must also include a take_with_food key. This is a boolean specifying whether or not the medication must be taken with food. true means it must be taken with food, false means it must not be taken with food, and null means it does not matter. Note that false means the medication must not be taken with food, not that it just doesn’t matter. So if unknown, take_with_food should be null.

Finally the schedule must include take_with_medications and take_without_medications keys. These should be arrays of integers that are the IDs of medications with which this medication must (or must not) be taken simultaneously with. If there are no medications like this, they should both be [].

Note that each medication object is also returned from the API with schedule_summary string field, containing human-readable text representing the schedule the medication should be taken on (e.g,. "Daily until 7/30/15"). schedule_summary will not denote whether the medication is as-needed unless it is as-needed only, in which case it will say "As needed only".

Authorization: Bearer ACCESS_TOKEN

{
    name: "Loratadine",
    rx_norm: "324026",
    ndc: "33261-0228",
    dose: {
        quantity: 100,
        unit: "mg"
    },
    route: "oral",
    form: "pill",
    rx_number: "123456789",
    fill_date: "2015-05-01",
    quantity: 50,
    type: "OTC",
    brand: "Claritin",
    origin: "manual",
    schedule: {
        as_needed: false,
        regularly: true,
        until: { type: "forever" },
        frequency: { n: 1, unit: "day" },
        times: [
            { type: "event", event: "breakfast", when: "before" },
            { type: "event", event: "breakfast", when: "after" },
            { type: "event", event: "lunch", when: "before" },
            { type: "event", event: "lunch", when: "after" },
            { type: "event", event: "dinner", when: "before" },
            { type: "event", event: "dinner", when: "after" },
            { type: "event", event: "sleep", when: "before" },
            { type: "event", event: "sleep", when: "after" },
            { type: "exact", time: "09:00" },
            { type: "exact", time: "21:30" },
            { type: "unspecified" }
        ],
        take_with_food: null,
        take_with_medications: [],
        take_without_medications: []
    },
    access_anyone: "default",
    access_family: "default",
    access_prime: "default",
    doctor_id: 1,
    pharmacy_id: 1,
    notes: "Love this med!!"
}

{
    id: 1,
    name: "Loratadine",
    rx_norm: "324026",
    ndc: "33261-0228",
    dose: {
        quantity: 100,
        unit: "mg"
    },
    route: "oral",
    form: "pill",
    rx_number: "123456789",
    fill_date: "2015-05-01",
    number_left: 17,
    quantity: 50,
    type: "OTC",
    brand: "Claritin",
    origin: "manual",
    schedule: {
        as_needed: false,
        regularly: true,
        until: { type: "forever" },
        frequency: { n: 1, unit: "day" },
        times: [
            { id: 1, type: "event", event: "breakfast", when: "before" },
            { id: 2, type: "event", event: "breakfast", when: "after" },
            { id: 3, type: "event", event: "lunch", when: "before" },
            { id: 4, type: "event", event: "lunch", when: "after" },
            { id: 5, type: "event", event: "dinner", when: "before" },
            { id: 6, type: "event", event: "dinner", when: "after" },
            { id: 7, type: "event", event: "sleep", when: "before" },
            { id: 8, type: "event", event: "sleep", when: "after" },
            { id: 9, type: "exact", time: "09:00" },
            { id: 10, type: "exact", time: "21:30" },
            { id: 11, type: "unspecified" }
        ],
        take_with_food: null,
        take_with_medications: [],
        take_without_medications: []
    },
    schedule_summary: "Daily",
    access_anyone: "default",
    access_family: "default",
    access_prime: "default",
    doctor_id: 1,
    pharmacy_id: 1,
    notes: "Love this med!!",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    medications: [
        {
            id: 1,
            name: "Loratadine",
            rx_norm: "324026",
            ndc: "33261-0228",
            dose: {
                quantity: 100,
                unit: "mg"
            },
            route: "oral",
            form: "pill",
            rx_number: "123456789",
            fill_date: "2015-05-01",
            number_left: 17,
            quantity: 50,
            type: "OTC",
            brand: "Claritin",
            origin: "manual",
            schedule: {
                as_needed: false,
                regularly: true,
                until: { type: "forever" },
                frequency: { n: 1, unit: "day" },
                times: [
                    { id: 1, type: "event", event: "breakfast", when: "before" },
                    { id: 2, type: "event", event: "breakfast", when: "after" },
                    { id: 3, type: "event", event: "lunch", when: "before" },
                    { id: 4, type: "event", event: "lunch", when: "after" },
                    { id: 5, type: "event", event: "dinner", when: "before" },
                    { id: 6, type: "event", event: "dinner", when: "after" },
                    { id: 7, type: "event", event: "sleep", when: "before" },
                    { id: 8, type: "event", event: "sleep", when: "after" },
                    { id: 9, type: "exact", time: "09:00" },
                    { id: 10, type: "exact", time: "21:30" },
                    { id: 11, type: "unspecified" }
                ],
                take_with_food: null,
                take_with_medications: [],
                take_without_medications: []
            },
            schedule_summary: "Daily",
            access_anyone: "default",
            access_family: "default",
            access_prime: "default",
            doctor_id: 1,
            pharmacy_id: 1,
            notes: "Love this med!!"
        },
        ...
    ],
    count: 7,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    name: "Loratadine",
    rx_norm: "324026",
    ndc: "33261-0228",
    dose: {
        quantity: 100,
        unit: "mg"
    },
    route: "oral",
    form: "pill",
    rx_number: "123456789",
    fill_date: "2015-05-01",
    number_left: 17,
    quantity: 50,
    type: "OTC",
    brand: "Claritin",
    origin: "manual",
    schedule: {
        as_needed: false,
        regularly: true,
        until: { type: "forever" },
        frequency: { n: 1, unit: "day" },
        times: [
            { id: 1, type: "event", event: "breakfast", when: "before" },
            { id: 2, type: "event", event: "breakfast", when: "after" },
            { id: 3, type: "event", event: "lunch", when: "before" },
            { id: 4, type: "event", event: "lunch", when: "after" },
            { id: 5, type: "event", event: "dinner", when: "before" },
            { id: 6, type: "event", event: "dinner", when: "after" },
            { id: 7, type: "event", event: "sleep", when: "before" },
            { id: 8, type: "event", event: "sleep", when: "after" },
            { id: 9, type: "exact", time: "09:00" },
            { id: 10, type: "exact", time: "21:30" },
            { id: 11, type: "unspecified" }
        ],
        take_with_food: null,
        take_with_medications: [],
        take_without_medications: []
    },
    schedule_summary: "Daily",
    access_anyone: "default",
    access_family: "default",
    access_prime: "default",
    doctor: {
        id: 1,
        name: "Dr. Y",
        phone: "(716) 716-7166",
        address: "Doctor Street, DC, 20052",
        notes: "Love this doc the most!",
        success: true
    },
    pharmacy: {
        name: "Pharmacy X",
        address: "Pharmacy Street, DC, 20052"
        phone: "(617) 617-6177",
        hours: {
            monday: {
                open: "0900",
                close: "1700"
            },
            tuesday: {
                open: "0900",
                close: "1700"
            },
            wednesday: {
                open: "0900",
                close: "1700"
            },
            thursday: {
                open: "0900",
                close: "1700"
            },
            friday: {
                open: "0900",
                close: "1700"
            },
            saturday: {
                open: "0900",
                close: "1700"
            },
            sunday: {
                open: "0900",
                close: "1700"
            },
            notes: "Great pharmacy! Love the smell"
        },
        notes: "Love this med!!"
    },
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    name: "Fexofenadine",
    rx_norm: "12345",
    ndc: "1234-6789",
    dose: {
        quantity: 120,
        unit: "mg"
    },
    route: "oral",
    form: "pill",
    rx_number: "123456789",
    fill_date: "2015-05-01",
    quantity: 50,
    type: "OTC",
    brand: "Claritin",
    origin: "manual",
    schedule: {
        as_needed: true,
        regularly: false
    },
    access_anyone: "write",
    access_family: "write",
    access_prime: "write",
    doctor_id: 1,
    pharmacy_id: 1,
    notes: "Great!"
}

{
    id: 1,
    name: "Fexofenadine",
    rx_norm: "12345",
    ndc: "1234-6789",
    dose: {
        quantity: 120,
        unit: "mg"
    },
    route: "oral",
    form: "pill",
    rx_number: "123456789",
    fill_date: "2015-05-01",
    number_left: 17,
    quantity: 50,
    type: "OTC",
    brand: "Claritin",
    origin: "manual",
    schedule: {
        as_needed: true,
        regularly: false
    },
    access_anyone: "write",
    access_family: "write",
    access_prime: "write",
    doctor_id: 1,
    pharmacy_id: 1,
    notes: "Great!",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    name: "Loratadine",
    rx_norm: "324026",
    ndc: "33261-0228",
    dose: {
        quantity: 100,
        unit: "mg"
    },
    route: "oral",
    form: "pill",
    rx_number: "123456789",
    fill_date: "2015-05-01",
    number_left: 17,
    quantity: 50,
    type: "OTC",
    brand: "Claritin",
    origin: "manual",
    schedule: {
        as_needed: false,
        regularly: true,
        until: { type: "forever" },
        frequency: { n: 1, unit: "day" },
        times: [
            { id: 1, type: "event", event: "breakfast", when: "before" },
            { id: 2, type: "event", event: "breakfast", when: "after" },
            { id: 3, type: "event", event: "lunch", when: "before" },
            { id: 4, type: "event", event: "lunch", when: "after" },
            { id: 5, type: "event", event: "dinner", when: "before" },
            { id: 6, type: "event", event: "dinner", when: "after" },
            { id: 7, type: "event", event: "sleep", when: "before" },
            { id: 8, type: "event", event: "sleep", when: "after" },
            { id: 9, type: "exact", time: "09:00" },
            { id: 10, type: "exact", time: "21:30" },
            { id: 11, type: "unspecified" }
        ],
        take_with_food: null,
        take_with_medications: [],
        take_without_medications: []
    },
    schedule_summary: "Daily",
    access_anyone: "write",
    access_family: "write",
    access_prime: "write",
    doctor_id: 1,
    pharmacy_id: 1,
    notes: "Great!",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    default: 30,
    user: "default",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    default: 20,
    user: 15
}

{
    default: 20,
    user: 15,
    success: true
}

Dose Events ¶

A dose event is when the patient takes their medication (either when they’re supposed to, adhering, or not, non-adhering) or skips their medication.

Authorization: Bearer ACCESS_TOKEN

{
    medication_id: 1,
    date: "2015-05-31T19:27:09+00:00",
    taken: true,
    scheduled: 3,
    notes: "Feeling sleepy now!"
}

{
    id: 1,
    medication_id: 1,
    date: "2015-05-31T19:27:09+00:00",
    notes: "Feeling sleepy now!",
    taken: true,
    scheduled: 3,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    doses: [
        {
            id: 1,
            medication_id: 1,
            date: "2015-05-31T19:27:09+00:00",
            taken: true,
            scheduled: 3,
            notes: "Feeling sleepy now!"
        },
        ...
    ],
    count: 46,
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    date: "2015-05-31T19:27:09+00:00",
    notes: "Feeling sleepy now!",
    taken: true,
    scheduled: 3,
    medication: {
        id: 1,
        name: "Loratadine",
        rx_norm: "324026",
        ndc: "33261-0228",
        dose: {
            quantity: 100,
            unit: "mg"
        },
        route: "oral",
        form: "pill",
        rx_number: "123456789",
        quantity: 50,
        type: "OTC",
        schedule: {
            ...
        },
        doctor_id: 1,
        pharmacy_id: 1,
        success: true
    },
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    medication_id: 1,
    date: "2015-05-31T19:27:09+00:00",
    taken: true,
    scheduled: 3,
    notes: "Not sleepy from this - forgot I took a melatonin pill earlier!"
}

{
    id: 1,
    medication_id: 1,
    date: "2015-05-31T19:27:09+00:00",
    taken: true,
    scheduled: 3,
    notes: "Not sleepy from this - forgot I took a melatonin pill earlier!",
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    id: 1,
    medication_id: 1,
    date: "2015-05-31T19:27:09+00:00",
    taken: true,
    scheduled: 3,
    notes: "Feeling sleepy now!"
    success: true
}

Authorization: Bearer ACCESS_TOKEN

{
    min_dose_date: "2015-04-01T15:29:09.000-04:00",
    count: 46,
    success: true
}

Schedule ¶

Authorization: Bearer ACCESS_TOKEN

// This illustrates a response when the current date falls somewhere
// in the middle of the specified date range. In other cases, either
// the first or second type of schedule datums would of course not be present.
{
    schedule: [
        {
            type: "time",
            date: "2015-03-31T19:27:09+00:00",
            notification: "2015-03-31T18:57:09+00:00",
            medication_id: 1,
            took_medication: true,
            delay: -17,
            dose_id: 14,
            take_with_food: true,
            take_with_medications: [1],
            take_without_medications: [3]
        },
        {
            type: "time",
            date: "2015-03-31T19:27:09+00:00",
            notification: "2015-03-31T18:57:09+00:00",
            medication_id: 1,
            took_medication: false,
            take_with_food: null,
            take_with_medications: [],
            take_without_medications: []
        },
        {
            type: "time",
            date: "2015-03-31T19:27:09+00:00",
            notification: "2015-03-31T18:57:09+00:00",
            medication_id: 1,
            took_medication: false,
            take_with_food: null,
            take_with_medications: [],
            take_without_medications: []
        },
        ... // more events that have already taken place
        {
            type: "time",
            date: "2015-05-31T19:27:09+00:00",
            notification: "2015-03-31T18:57:09+00:00",
            medication_id: 1,
            take_with_food: null,
            take_with_medications: [],
            take_without_medications: []
        },
        {
            // no time specified, just the date
            type: "date",
            date: "2015-05-31",
            notification: "2015-03-31T18:57:09+00:00",
            medication_id: 3,
            take_with_food: null,
            take_with_medications: [],
            take_without_medications: []
        },
        ... // more events in the future
    ],
    // only present if some events have already taken place
    statistics: {
        took_medication: 70.3,
        delay: 4,
        delta: -1
    },
    success: true
}

NPI ¶

Uses the BloomAPI to look up provider information in the National Plan and Provider Enumeration System (NPPES).

{
    business_address: {
        address_details_line: "2ND FLOOR",
        address_line: "2350 W EL CAMINO REAL",
        city: "MOUNTAIN VIEW",
        country_code: "US",
        state: "CA",
        zip: "940406203"
    },
    credential: "MD",
    enumeration_date: "2006-08-31T00:00:00.000Z",
    first_name: "HARRY",
    gender: "male",
    last_name: "DENNIS",
    last_update_date: "2012-01-10T00:00:00.000Z",
    npi: 1073624029,
    practice_address: {
        address_line: "795 EL CAMINO REAL",
        city: "PALO ALTO",
        country_code: "US",
        phone: "6508532992",
        state: "CA",
        zip: "943012302"
    },
    provider_details: [{
        healthcare_taxonomy_code: "208000000X",
        license_number: "G68571",
        license_number_state: "CA",
        taxonomy_switch: "yes"
    }],
    sole_proprietor: "no",
    type: "individual"
}

{
    name: [{
        first: "Harry", //String, Optional
        last: "Dennis" //String, required
    }],
    address: [{
        state: "CA" //String, optional
    }]
}

{
    providers: [ 
        {
            business_address: {
                address_details_line: "2ND FLOOR",
                address_line: "2350 W EL CAMINO REAL",
                city: "MOUNTAIN VIEW",
                country_code: "US",
                state: "CA",
                zip: "940406203"
            },
            credential: "MD",
            enumeration_date: "2006-08-31T00:00:00.000Z",
            first_name: "HARRY",
            gender: "male",
            last_name: "DENNIS",
            last_update_date: "2012-01-10T00:00:00.000Z",
            npi: 1073624029,
            practice_address: {
                address_line: "795 EL CAMINO REAL",
                city: "PALO ALTO",
                country_code: "US",
                phone: "6508532992",
                state: "CA",
                zip: "943012302"
            },
            provider_details: [{
                healthcare_taxonomy_code: "208000000X",
                license_number: "G68571",
                license_number_state: "CA",
                taxonomy_switch: "yes"
            }],
            sole_proprietor: "no",
            type: "individual"
        },
        ...
    ],
    count: 3,
    success: true
}

RXNorm ¶

Uses the RXNorm and OpenFDA APIs to look up medication details. An example flow would be to search by name using the /group endpoint. If no results are found, then search for spelling suggestions using the /spelling endpoint, and use the results to search by the correct name using the /group endpoint.

{
    medname: "Allegra-D"
}

{
    result: {
        drugGroup: {
            name: "Allegra-D",
            conceptGroup: [
                {
                    tty: "BPCK"
                },
                {
                    tty: "SBD",
                    conceptProperties: [
                        {
                            rxcui: "997512",
                            name: "12 HR Fexofenadine hydrochloride 60 MG / Pseudoephedrine Hydrochloride 120 MG Extended Release Oral Tablet [Allegra-D]",
                            synonym: "Allegra-D 12 Hour (fexofenadine hydrochloride 60 MG / pseudoephedrine hydrochloride 120 MG) Extended Release Oral Tablet",
                            tty: "SBD",
                            language: "ENG",
                            suppress: "N",
                            umlscui: "C0716180",
                            dfg: ["Oral Tablet"],
                            brand: "Allegra-D",
                            modifiedname: "12 HR Fexofenadine hydrochloride 60 MG / Pseudoephedrine Hydrochloride 120 MG Extended Release  "
                        }, {
                            rxcui: "997515",
                            name: "24 HR Fexofenadine hydrochloride 180 MG / Pseudoephedrine Hydrochloride 240 MG Extended Release Oral Tablet [Allegra-D]",
                            synonym: "Allegra-D 24 Hour (fexofenadine hydrochloride 180 MG / pseudoephedrine hydrochloride 240 MG) Extended Release Oral Tablet",
                            tty: "SBD",
                            language: "ENG",
                            suppress: "N",
                            umlscui: "C1616745",
                            dfg: ["Oral Tablet"],
                            brand: "Allegra-D",
                            modifiedname: "24 HR Fexofenadine hydrochloride 180 MG / Pseudoephedrine Hydrochloride 240 MG Extended Release  "
                        }
                    ]
                }
            ]
        },
        compiled: [
            {
                rxcui: "997512",
                name: "12 HR Fexofenadine hydrochloride 60 MG / Pseudoephedrine Hydrochloride 120 MG Extended Release Oral Tablet [Allegra-D]",
                synonym: "Allegra-D 12 Hour (fexofenadine hydrochloride 60 MG / pseudoephedrine hydrochloride 120 MG) Extended Release Oral Tablet",
                tty: "SBD",
                language: "ENG",
                suppress: "N",
                umlscui: "C0716180",
                dfg: ["Oral Tablet"],
                brand: "Allegra-D",
                modifiedname: "12 HR Fexofenadine hydrochloride 60 MG / Pseudoephedrine Hydrochloride 120 MG Extended Release  "
            },
            {
                rxcui: "997515",
                name: "24 HR Fexofenadine hydrochloride 180 MG / Pseudoephedrine Hydrochloride 240 MG Extended Release Oral Tablet [Allegra-D]",
                synonym: "Allegra-D 24 Hour (fexofenadine hydrochloride 180 MG / pseudoephedrine hydrochloride 240 MG) Extended Release Oral Tablet",
                tty: "SBD",
                language: "ENG",
                suppress: "N",
                umlscui: "C1616745",
                dfg: ["Oral Tablet"],
                brand: "Allegra-D",
                modifiedname: "24 HR Fexofenadine hydrochloride 180 MG / Pseudoephedrine Hydrochloride 240 MG Extended Release  "
            }
        ],
        dfg: ["Oral Tablet"],
        brand: ["Allegra-D"]
    },
    success: true
}

{
    medname: "allegrad"
}

{
    result: {
        suggestionGroup: {
            name: "allegrad",
            suggestionList: {
                suggestion: ["Allegra-D", "Allegra", "Allermax", "Alera", "Alkeran", "Aloeguard"]
            }
        }
    },
    success: true
}