# 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](http://www.iana.org/time-zones), 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 | {% tabs %} {% tab title="Example Account Object" %} ```javascript { "_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" } ``` {% endtab %} {% endtabs %} ## List `GET` `https://api.dev.medable.com/your_org_name/v2/accounts` Retrieve all accounts #### Path Parameters | Name | Type | Description | | --------------- | ------ | ----------- | | your\_org\_name | string | | {% tabs %} {% tab title="200 " %} ``` { "data": [ { "_id": "5525fc2db7995d2c2807632a", "object": "account", "name": { "first": "Charles", "last": "Best" } }, { "_id": "552352a4ea05b030066583fc", "object": "account", "name": { "first": "Charles", "last": "Best" } } ], "hasMore": false, "object": "list" } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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 | | {% tabs %} {% tab title="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" } } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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 | | {% tabs %} {% tab title="200 " %} ``` { "_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" } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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) | {% tabs %} {% tab title="200 " %} ``` { "_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" } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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 | 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. | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ```javascript $.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 | Name | Type | Description | | --------------- | ------ | ----------- | | your\_org\_name | string | | {% tabs %} {% tab title="200 " %} ``` { "object": "result", "data": true } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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 | | {% tabs %} {% tab title="200 " %} ``` { "object":"result", "data":true } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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 {% hint style="info" %} You can override the destination link in part 4 to be your own page on your own domain for app look and feel consistency. {% endhint %} ## 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 | {% tabs %} {% tab title="200 " %} ``` { "object": "result", "data": { "fingerprint": "b8342060-e409-11e4-bcc2-c71dd7c9f996", "secret": "CO6PrBDwrNnXdIizD2LasmNHnpJIw8Xd" } } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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 | | {% tabs %} {% tab title="200 " %} ``` { "object":"result", "data":true } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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 | | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ```javascript $.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 | | {% tabs %} {% tab title="200 " %} ``` { "object": "result", "data": true } ``` {% endtab %} {% tab title="409 " %} ``` { "object":"result", "data": { "object": "fault", "name": "error", "code": "kExists", "status": 409, "reason": "Account already verified" } } ``` {% endtab %} {% endtabs %} ```javascript $.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 | | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ```javascript $.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) { // ... }); ``` {% hint style="warning" %} Due to security reasons, we do not allow modifying of the email address of a given account. {% endhint %} ## 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 | | {% tabs %} {% tab title="200 " %} ```javascript { "_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" } } ``` {% endtab %} {% tab title="400 " %} ``` {} ``` {% endtab %} {% endtabs %} ```javascript $.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) { // ... }); ```