Accounts

Learn how to create accounts, verify and update your personal details

As soon as you create an account, it can be used to login in their Accounts page and (in case of developers) their Developer console. It can also be used to login to the CMS App after it has been verified

Verifying an account's login credentials

As soon as the account is created, a verification email (if created with an email) and/or sms (if created with mobileNo that is a Philippine mobile number) will be sent. The email (or sms message) will contain a verification code that can be used to verify the account's login credential(s) (email and/or mobileNo) using the authentication API's create method (applyActionCode action)

Email onboarding

New accounts (signed up with email) can expect to receive the following emails:

• Welcome Email upon account creation
• Human Verification Email upon account creation for a doctor (PersonalDetails#doc_PRCLicense is provided)
• Email Verification upon creation of non-doctors using an email identity

Other emails that can be recieved

• Identity validation receipt when identity images (PersonalDetails#identityImages) are provided
• Facility Membership Invitation when invited by an existing facility
• Patient Account Connection when invited by permitted account to associate an existing patient to its owner's account

Creating Accounts

Each Account has a corresponding PersonalDetails (Account.uid will match PersonalDetails.id). If the PersonalDetails.doc_PRCLicenseNo is truthy (exists, value is not null or 0), Account.isDoctor will be true. When creating an Account, a personalDetails field can be provided to populate the PersonalDetails. Take the following minimal example payload for /accounts:

curl <base-uri>/accounts \
-X POST \
-H 'Content-Type: application/json' \
-d '{
    "email": "test@mail.com",
    "password": "password",
    "personalDetails": {
        "doc_PRCLicenseNo": 1234,
    }
}'

curl <base-uri>/accounts \
-X POST \
-H 'Content-Type: application/json' \
-d '{
    "email": "test@mail.com",
    "password": "password",
    "personalDetails": {
        "doc_PRCLicenseNo": 1234,
    }
}'

Here, the Account will be created, as well as the PersonalDetails with the correct doc_PRCLicenseNo.

Caveats

• accounts cannot be created on on-premise servers

Change login identity

An account's login identity (email and/or mobileNo) can only be changed using the authentication API's create method (changeIdentity action). It will then send a Confirm Change Identity email that will contain a code that should be applied using the (authentication API)[https://developers.example.com/docs/api#authentication]'s create method (applyActionCode action)

Passwords

Passwords are supplied only on creation (signup) and will then not be available for viewing anymore. It is stored in the database in a hashed format (using bcyrpt) that is only useful to verify if a provided input (on signin) is the same but cannot be used to derive the password itself.

Change password

An account's password can only be changed using the authentication API's create method (changePassword action). It will then send a Confirm Password Change email that will contain a code that should be applied using the authentication API's create method (applyActionCode action)

Update personal details

Login credential(s) verified account can change their personal details using the personal-details API;

QR Code

Generates a JWT encoding selected data (set per service) including an access token that can be used to fetch the associated document without loggin in a privileged user.

Encoding

# trigger the operator
GET /accounts/random-account-uid?$generateQRCode=true

# responsed with a JWT which is expected to be encoded
# in the fronted to a QR image
ey****.***.***

# trigger the operator
GET /accounts/random-account-uid?$generateQRCode=true

# responsed with a JWT which is expected to be encoded
# in the fronted to a QR image
ey****.***.***

Scanning and Parsing

The QR code must be decoded and parsed as a JWT. This JWT contains the ff standard fields (w/c may include additional fields depending on the service)

• typ the type of the JWT which is usually the service where the QR code was generated
• sub id of the document associated to the JWT
• accessToken (optional) access token that can be used to re/query all relevant encoded data in the JWT

const decodedFromQRCode = 'ey***.***.****';
const payload = parsedJWTPayload(decodedFromQRCode);
// { typ: 'account', sub: 'random-account-uid', name: 'FirstName, LastName', accessToken: 'ey****.***.***' }

const requeried = await http.get(`/accounts/${payload.sub}`, {
  headers: { Authorization: `Bearer ${payload.accessToken}` }
});
// { uid: 'random-account-uid', email: 'random@domain.com', ... }

const decodedFromQRCode = 'ey***.***.****';
const payload = parsedJWTPayload(decodedFromQRCode);
// { typ: 'account', sub: 'random-account-uid', name: 'FirstName, LastName', accessToken: 'ey****.***.***' }

const requeried = await http.get(`/accounts/${payload.sub}`, {
  headers: { Authorization: `Bearer ${payload.accessToken}` }
});
// { uid: 'random-account-uid', email: 'random@domain.com', ... }

Waitlist

In invite-only signup mode, an account can only be created by adding an invitation code in the creation payload. Aside from the application admins sending invite codes to select users, a user can request to be added to a waitlist to be approved by application admins (sending them the codes) An email can be added to the waitlist using the account-waitlist API's create method.

Signup with invite code

Additional details provided when adding an email in the waitlist can be fetched (using the invite code as id) to prefill the signup page/payload for the account (if mobileNo, name, etc...) using the account-waitlist API's get method.

Account Referrals

accounts can create referral codes that they can share to others such that when those given the codes sign up using said code, the referrer would receive rewards (set by the system) such as points

Creating account referral codes

POST /account-invitations
{
  "type": "account-referral"
}

## respondes with
{
  "id": "6-char-referral/invitation-code"
}

POST /account-invitations
{
  "type": "account-referral"
}

## respondes with
{
  "id": "6-char-referral/invitation-code"
}

Fetching an account's existing referral codes

# all referral codes created by the account
GET /account-invitations?createdBy=<account-uid>&type=account-referral

# all referral codes that can be reused
# sdk.service('account-invitations').find({
#   type: 'account-referral',
#   createdBy: <account.uid>,
#   email: null,
# })
GET /account-invitations?createdBy=<account-uid>&type=account-referral&email=

# all referral codes created by the account
GET /account-invitations?createdBy=<account-uid>&type=account-referral

# all referral codes that can be reused
# sdk.service('account-invitations').find({
#   type: 'account-referral',
#   createdBy: <account.uid>,
#   email: null,
# })
GET /account-invitations?createdBy=<account-uid>&type=account-referral&email=

Signup using account referral codes

POST /accounts
{
  "email": "referred@test.com",
  "password": "strongpassword",

  # referral/invite code
  "invitation": "6-char-referral/invitation-code",

  # ...other signup payload
}

POST /accounts
{
  "email": "referred@test.com",
  "password": "strongpassword",

  # referral/invite code
  "invitation": "6-char-referral/invitation-code",

  # ...other signup payload
}

Referrer points

points collected per account can be viewed by fetching its associated RewardPoints records

GET /rewards/points/<referrer-uid>

{
  "id": "uid-of-the-referrer",
  "account": "uid-of-the-referrer",
  "amount": 250,
}

GET /rewards/points/<referrer-uid>

{
  "id": "uid-of-the-referrer",
  "account": "uid-of-the-referrer",
  "amount": 250,
}