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

Example Account Object

{
    "_id": "54c66edac364f2201b78c34e",
    "access": 6,
    "dob": "1975-01-26",
    "email": "[e-mail]",
    "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

Name	Type	Description
your_org_name	string

200

{
    "data": [
        {
            "_id": "5525fc2db7995d2c2807632a",
            "object": "account",
            "name": {
                "first": "Charles",
                "last": "Best"
            }
        },
        {
            "_id": "552352a4ea05b030066583fc",
            "object": "account",
            "name": {
                "first": "Charles",
                "last": "Best"
            }
        }
    ],
    "hasMore": false,
    "object": "list"
}

400

{}

$.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

Name	Type	Description
account_id	string
your_org_name	string

200

{
    "_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"
    }
}

400

{}

$.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

Name	Type	Description
your_org_name	string

200

{
    "_id": "552352a4ea05b030066583fc",
    "access": 6,
    "dob": "1899-02-27",
    "email": "[e-mail]",
    "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"
}

400

{}

$.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

Name	Type	Description
your_org_name	string

Request Body

Name	Type	Description
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)

200

{
    "_id": "552352a4ea05b030066583fc",
    "access": 6,
    "dob": "1899-02-27",
    "email": "[e-mail]",
    "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"
}

400

{}

$.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": "[e-mail]",
    "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

Name	Type	Description
your_org_name	string

Request Body

Name	Type	Description
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.

200

$.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": "[e-mail]",
    "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

Name	Type	Description
your_org_name	string

200

{
    "object": "result",
    "data": true
}

400

{}

$.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

Name	Type	Description
your_org_name	string

Request Body

Name	Type	Description
email	string

200

{
    "object":"result",
    "data":true
}

400

{}

$.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": "[e-mail]"
}
}).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

Name	Type	Description
your_org_name	string

Request Body

Name	Type	Description
current	string	this is the old (current) password
password	string	this is the new password

200

{
    "object": "result",
    "data": {
        "fingerprint": "b8342060-e409-11e4-bcc2-c71dd7c9f996",
        "secret": "CO6PrBDwrNnXdIizD2LasmNHnpJIw8Xd"
    }
}

400

{}

$.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

Name	Type	Description
your_org_name	string

Request Body

Name	Type	Description
password	string
token	string

200

{
    "object":"result",
    "data":true
}

400

{}

$.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

Name	Type	Description
token	string	The email verification process generates a token that can be passed in to mark an email as verified.
your_org_name	string

200

$.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

Name	Type	Description
your_org_name	string

200

{
    "object": "result",
    "data": true
}

409

{
    "object":"result",
    "data": {
        "object": "fault",
        "name": "error",
        "code": "kExists",
        "status": 409,
        "reason": "Account already verified"
    }
}

$.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

Name	Type	Description
your_org_name	string
account_id	string

Request Body

Name	Type	Description
name	string
first	string
last	string
mobile	string
dob	string
gender	string
any account property	string

200

$.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

Name	Type	Description
your_org_name	string
account_id	string

Request Body

Name	Type	Description
op	string
path	string
value	string

200

{
    "_id": "586eb9ef64129a5f3631a0ca",
    "access": 6,
    "created": "2016-01-05T21:26:07.292Z",
    "email": "[e-mail]",
    "favorite": false,
    "gender": "m",
    "inherited_roles": [
        "000000000000000000000007",
        "000000000000000000000006"
    ],
    "key": {
        "fingerprint": "a15aecd0-d394-11e6-9754-5f93dce3d489",
        "secret": "fDQEdMnfqxmFvCBtHpl7FWPnxcUTaBOl"
    },
    "locale": "en_US",
    "locked": false,
    "mobile": "[phone]",
    "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"
    }
}

400

{}

$.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) {
    // ...
});