Account

The Account Object represents a user account within an Organization.

_id ObjectId

The account identifier.

access Number

The current caller's context access level.

activationRequired Boolean

True if the account must be activated before use. Dependant on Org settings.

age Number

The age of the account holder (based on the dob property).

connections Reference[]

Connections associated with the Account.

created Date

The date the context was created.

dob Date

Account holder date of birth.

email* String

The email address for the account and must be unique within the Org.

favorite Boolean

Tags the context as a favorite, which can then be filtered using the API.

gender String

Account holder gender. Available values are: f - Female m - Male n - Neither o - Other t - Trans u - Unspecified

image File

The account profile image.

inherited_roles ObjectId[]

Any roles that are inherited from my current role. If my current role has no sub-roles then this is an empty array.

key Document

A fingerprint and secret, re-generated on password change. Useful for client-side PHI encryption/caching scenarios, it is available to the account holder for the life of an authenticated session.

mobile String

The mobile number of the account holder. This number should be capable of receiving SMS messages and must be in E.164 format.

name Document

Name of the account holder (split into first and last names as well as optional prefix, middle, suffix and additional[]).

object String

The context’s object name.

preferences Document

The account preferences.

profile Document

The account profile.

roles ObjectId[]

Account roles (e.g. Provider, Administrator, Developer). Accounts can have more than one role.

shared Boolean

True if there are any active or pending connections for this context.

state String

Current state for the account. (e.g. unverified, verified)

tz String

Timezone for the account. This helps determine UTC offset when working in scripts. The timezone must by a unique identifier for an IANA assigned zone, e.g. "US/Pacific"

updated Date

The date the latest update was made to a context’s properties

updater Reference

The account id of the context updater

{
    "_id": "54c66edac364f2201b78c34e",
    "access": 6,
    "dob": "1975-01-26",
    "email": "john.smith@example.com",
    "favorite": false,
    "gender": "m",
    "key": {
        "fingerprint": "094be6f0-a57b-11e4-9323-d35446f5af36",
        "secret": "P07uqKLlXDWjj3s85TGJt4BXSuSCFlpx"
    },
    "locale": "en_US",
    "locked": false,
    "mobile": "15551234567",
    "name": {
        "first": "John",
        "last": "Smith"
    },
    "object": "account",
    "preferences": {
        "notifications": [
            {
                "label": "Custom Notifier",
                "name": "c_notifier",
                "_id": "56cbfddcba9ef5257bf48513",
                "endpoints": [
                    {
                        "_id": "456e64706f696e7420536d73",
                        "enabled": false,
                        "label": "SMS",
                        "name": "sms"
                    },
                    {
                        "_id": "456e64706f696e7420456d6c",
                        "enabled": true,
                        "label": "Email",
                        "name": "email"
                    }
                ]
            }
        ]
    },
    "profile": {
        "provider": {
            "affiliation": "None",
            "license": {
                "number": "777",
                "state": "Alabama"
            },
            "npi": "798798798",
            "specialty": "Allergy and Immunology",
            "state": "processing",
            "visibility": {
                "provider": false,
                "public": false
            }
        }
    },
    "roles": [
        "000000000000000000000005"
    ],
    "shared": false,
    "state": "verified",
    "updated": "2015-03-12T18:47:34.010Z"
}

List

GET https://api.dev.medable.com/your_org_name/v2/accounts

Retrieve all accounts

Path Parameters

NameTypeDescription

your_org_name

string

{
    "data": [
        {
            "_id": "5525fc2db7995d2c2807632a",
            "object": "account",
            "name": {
                "first": "Charles",
                "last": "Best"
            }
        },
        {
            "_id": "552352a4ea05b030066583fc",
            "object": "account",
            "name": {
                "first": "Charles",
                "last": "Best"
            }
        }
    ],
    "hasMore": false,
    "object": "list"
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts?paths[]=name",
    method: "GET",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Read

GET https://api.dev.medable.com/your_org_name/v2/accounts/account_id

Retrieve an account

Path Parameters

NameTypeDescription

account_id

string

your_org_name

string

{
    "_id": "5525fc2db7995d2c2807632a",
    "access": 2,
    "favorite": false,
    "image": {
        "ETag": "594b69d035ac27c2e69ef053082eb6a3",
        "creator": "5525fc2db7995d2c2807632a",
        "facets": [
            {
                "ETag": "047fb43a1389f6a00d06fdbbe8780a0c",
                "creator": "5525fc2db7995d2c2807632a",
                "height": 160,
                "location": 4,
                "mime": "image/jpeg",
                "name": "thumbnail",
                "path": "/accounts/5525fc2db7995d2c2807632a/image/thumbnail",
                "size": 7823,
                "state": 2,
                "width": 160
            }
        ],
        "height": 500,
        "location": 4,
        "mime": "image/jpeg",
        "name": "content",
        "path": "/accounts/5525fc2db7995d2c2807632a/image/content",
        "size": 52586,
        "state": 2,
        "width": 622
    },
    "name": {
        "first": "Charles",
        "last": "Best"
    },
    "object": "account",
    "shared": true,
    "updated": "2015-04-15T16:56:32.052Z",
    "updater": {
        "_id": "000000000000000000000002",
        "object": "account",
        "path": "/accounts/000000000000000000000002"
    }
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/5525fc2db7995d2c2807632a",
    method: "GET",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Current User

GET https://api.dev.medable.com/your_org_name/v2/accounts/me

Path Parameters

NameTypeDescription

your_org_name

string

{
    "_id": "552352a4ea05b030066583fc",
    "access": 6,
    "dob": "1899-02-27",
    "email": "charles.best@example.org",
    "favorite": false,
    "gender": "m",
    "key": {
        "fingerprint": "69521070-dcd8-11e4-98e9-c5a28d7729c2",
        "secret": "cUdg8LCspNtSVDPCdr281oD6c2PO0EVW"
    },
    "locale": "en_US",
    "locked": false,
    "mobile": "16505555555",
    "name": {
        "first": "Charles",
        "last": "Best"
    },
    "object": "account",
    "roles": [],
    "shared": false,
    "state": "unverified"
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/me",
    method: "GET",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Register

POST https://api.dev.medable.com/your_org_name/v2/accounts/register

Account Registration

Path Parameters

NameTypeDescription

your_org_name

string

Request Body

NameTypeDescription

name

object

first

string

This is attached to the name object.

last

string

This is attached to the name object.

email

string

This is later used with the password to log in

mobile

string

in E.164 format

password

string

Must meet org password strength requirements

dob

string

YYYY-MM-DD

gender

string

"m" or "f"

tz

string

The timezone for the user

token

object

Invite/connection token (if applicable)

{
    "_id": "552352a4ea05b030066583fc",
    "access": 6,
    "dob": "1899-02-27",
    "email": "charles.best@example.org",
    "favorite": false,
    "gender": "m",
    "key": {
        "fingerprint": "69521070-dcd8-11e4-98e9-c5a28d7729c2",
        "secret": "cUdg8LCspNtSVDPCdr281oD6c2PO0EVW"
    },
    "locale": "en_US",
    "locked": false,
    "mobile": "16505555555",
    "name": {
        "first": "Charles",
        "last": "Best"
    },
    "object": "account",
    "roles": [],
    "shared": false,
    "state": "unverified"
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/register",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    },
    data: {
    "name": {
        "first": "Charles",
        "last": "Best"
    },
    "email": "charles.best@example.org",
    "gender": "m",
    "dob": "1899-02-27",
    "mobile": "1-650-555-5555",
    "password": "Thanks for the break, Banting!"
}
}).done(function(data) {
    // ...
});

Login

POST https://api.dev.medable.com/your_org_name/v2/accounts/login

Path Parameters

NameTypeDescription

your_org_name

string

Request Body

NameTypeDescription

email

string

password

string

location

object

verificationToken

string

6 digit verification token sent to user's mobile device for 2FA. Attached to location object.

locationName

string

if you want to associate a string with a given authorized access point. Attached to location object.

singleUse

boolean

The equivalent of "Remember Me" checkbox common in login options. Attached to location object.

iosNotificationToken

string

The iOS notification token received from APN for push notifications (if applicable). Attached to location object.

gcmRegistrationId

string

The Android FCM/GCM push registration id (if applicable). Attached to location object.

$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/login",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    },
    data: {
    "email": "james@example.com",
    "password": "this is not my passphrase",
    "location": {
        "verificationToken": "123456",
        "locationName": "New Orleans",
        "singleUse": true
    }
}
}).done(function(data) {
    // ...
});

Logout

POST https://api.dev.medable.com/your_org_name/v2/accounts/me/logout

Invalidate the currently authenticated session

Path Parameters

NameTypeDescription

your_org_name

string

{
    "object": "result",
    "data": true
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/me/logout",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Request Password Reset

POST https://api.dev.medable.com/your_org_name/v2/accounts/request-password-reset

Request a password reset via email This endpoint would typically be used when a user is trying to login but cannot remember his/her password. They can simply enter their email address associated with the account (which gets passed into this endpoint) and an email will be automatically generated by Medable with the proper link to set a new password.

Path Parameters

NameTypeDescription

your_org_name

string

Request Body

NameTypeDescription

email

string

{
    "object":"result",
    "data":true
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/request-password-reset",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    },
    data: {
    "email": "charles.best@medable.com"
}
}).done(function(data) {
    // ...
});

Example:

  1. Request Password Reset gets called

  2. Medable sends the email with a one-time secure reset password token (string)

  3. The user opens that email and clicks a link which has this token as a url parameter

  4. User gets navigated to a Medable web GUI for setting the new password

You can override the destination link in part 4 to be your own page on your own domain for app look and feel consistency.

Update My Password

POST https://api.dev.medable.com/your_org_name/accounts/me/update-password

Update the currently logged in user's password directly through the API This endpoint would typically be used for a currently logged in user who wants to change his/her password directly from your app without having to go through the email password reset flow.

Path Parameters

NameTypeDescription

your_org_name

string

Request Body

NameTypeDescription

current

string

this is the old (current) password

password

string

this is the new password

{
    "object": "result",
    "data": {
        "fingerprint": "b8342060-e409-11e4-bcc2-c71dd7c9f996",
        "secret": "CO6PrBDwrNnXdIizD2LasmNHnpJIw8Xd"
    }
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/me/update-password",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    },
    data: {
    "current": "this is not my passphrase",
    "password": "correct horse battery staple"
}
}).done(function(data) {
    // ...
});

Update Password (Token)

POST https://api.dev.medable.com/your_org_name/accounts/reset-password

This endpoint would typically be used if you wanted to build a custom page that is linked in the email reset.

Path Parameters

NameTypeDescription

your_org_name

string

Request Body

NameTypeDescription

password

string

token

string

{
    "object":"result",
    "data":true
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/reset-password",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    },
    data: {
    "token": "kPBg3AACpwTzhiOpUTz2i2koJqqot70M",
    "password": "here's a new passphrase!"
}
}).done(function(data) {
    // ...
});

Verify Email From Token

POST https://api.dev.medable.com/your_org_name/v2/token

Path Parameters

NameTypeDescription

token

string

The email verification process generates a token that can be passed in to mark an email as verified.

your_org_name

string

$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/lBMSJWtqKVdx8Z888syX6axpCk2j7eYm",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Resend Email Verification

POST https://api.dev.medable.com/your_org_name/v2/accounts/me/resend-verification

Path Parameters

NameTypeDescription

your_org_name

string

{
    "object": "result",
    "data": true
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/me/resend-verification",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Update

PUT https://api.dev.medable.com/your_org_name/v2/accounts/me/resend-verification

To modify a property on an Account object

Path Parameters

NameTypeDescription

your_org_name

string

account_id

string

Request Body

NameTypeDescription

name

string

first

string

last

string

mobile

string

dob

string

gender

string

any account property

string

$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/586eb9ef64129a5f3631a0ca",
    method: "PUT",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    },
    data: {
    "name": {
        "first":"Bob",
        "last":"Dole"
    }
}
}).done(function(data) {
    // ...
});

Due to security reasons, we do not allow modifying of the email address of a given account.

Update

PATCH https://api.dev.medable.com/your_org_name/v2/accounts/account_id

To modify a property on an Account object via PATCH

Path Parameters

NameTypeDescription

your_org_name

string

account_id

string

Request Body

NameTypeDescription

op

string

path

string

value

string

{
    "_id": "586eb9ef64129a5f3631a0ca",
    "access": 6,
    "created": "2016-01-05T21:26:07.292Z",
    "email": "john@medable.com",
    "favorite": false,
    "gender": "m",
    "inherited_roles": [
        "000000000000000000000007",
        "000000000000000000000006"
    ],
    "key": {
        "fingerprint": "a15aecd0-d394-11e6-9754-5f93dce3d489",
        "secret": "fDQEdMnfqxmFvCBtHpl7FWPnxcUTaBOl"
    },
    "locale": "en_US",
    "locked": false,
    "mobile": "+12223334444",
    "name": {
        "first": "John",
        "last": "Smith"
    },
    "object": "account",
    "roles": [
        "000000000000000000000004",
        "587012227d67efea0843fa80"
    ],
    "shared": false,
    "state": "verified",
    "updated": "2016-06-06T14:01:08.699Z",
    "updater": {
        "_id": "586eb9ef64129a5f3631a0ca",
        "object": "account",
        "path": "/accounts/586eb9ef64129a5f3631a0ca"
    }
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/586eb9ef64129a5f3631a0ca",
    method: "PATCH",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    },
    data: { 
      	"op": "push", 
      	"path": "/roles", 
      	"value": "587012227d67efea0843fa80" 
    }
}).done(function(data) {
    // ...
});

Last updated