/
account_exists ()

account_exists ()

Owned by Pedro Jose Sanchez Luling, created
Last updated: Sept 12, 2023
4 min read

Function prototype

account_exists (account, secret, [country_code = null], [team = null], [shared_key = null])

API Version

2.7.19 and higher

Supported interfaces

SOAP, REST

Description

Checks if the 'account_ref' provided is a valid login identifier (can be used to perform a session_init())

This function can be used prior to a call to session_init () to know wheter the account exists or not. If the account does not exist, it may be necessary to create a new account first (sign up).

When the account doesn’t exist, the function also indicates if it is allowed to create a new account.

This is useful in a 2-step login, where in a first step only the account name is entered, and the following step depends on the existence of the account:

  • If the account name exists, then the password is requested and session_init () can be invoked

  • If the account name doesn’t exist it is possible to offer the opportunity of creating a new account (if it is allowed to create a new account)

For security reasons, only authorised users who know the "secret" can call this function. The secret string is delivered by Linkcare only to authorised partners

Input parameters:

  • account: the login identifier that will be verified

  • secret: only authorised users who know the "secret" string can call this function.

  • country_code: Optional 2-letter ISO country code indicating the country of the user. This is necessary if the account parameter is a phone number without the country prefix, because the API will try to deduce the prefix from the country code. Introduced in API Version 2.7.28

  • team: A team reference. Introduced in API version 2.7.28. Used for 2 purposes:

    • Allows to indicate a TEAM IDENTIFIER for doing a login (A TEAM IDENTIFIER is a value that unique for a USER only in the context of a TEAM, but not globally unique)

    • For enrolling automatically a new patient in a SUBSCRIPTION (PROGRAM + TEAM). This happens when the team provided has a default PROGRAM assigned (see team_get () , team_set () )

  • shared_key: If it is planned to invoke session_init ()or account_create () with a shared key, it should also be passed to this function because it may make a difference to decide whether it is possible to create a new account or not. For example, if an invitation has been sent to a user to be an ASSOCIATE of a patient, that invitation will include a SHARED KEY OBJECT reference indicating that it is allowed to create a new account.

Output parameters:

  • result:  

    • exists: (true / false) indicates whether the account_ref provided is a valid login identifier

    • allow_signup: (true / false) When the account does not exist, or it exists but the user has never initiated a session, this field indicates whether it is allowed to do the sign-up process (by means of the account_create () function). The factors that decide whether it is possible to create a new account are:

      • The account exists internally because it has been created by a PROFESSIONAL, but not by the holder of the account. In this case the account holder has 2 options:

        • sign in (using the session_init () API function) using a default password (if a default password has been assigned to the account). The user will be prompted to change the default password

        • sign up (using the account_create () API function). A notification will be sent to the user via email or SMS to verify the user owns the account

      • There exists a SHARED KEY OBJECT (passed in the parameter shared_key) that contains an explicit invitation to create a new account (e.g. a new PROFESSIONAL or ASSOCIATE)

      • The new account is for a patient and there exists a default SUBSCRIPTION (PROGRAM + TEAM) in which the new patient will be enrolled automatically

  • ErrorMsg: If any error occurs, then this value contains a description of the error translated to the current language

  • ErrorCode: If any error occurs, then this value contains any of the standard ERROR CODES

Request example

instance_account_exists ("loginid", “kjsad9q734yhafsjk”); instance_account_exists ("loginid", “kjsad9q734yhafsjk”, "es");

Response

The response format is XML when the function has been invoked via the SOAP API, and JSON when it has been invoked via the REST API

Return Error codes

ERROR CODE

 

ERROR CODE

 

INSUFFICIENT_PRIVILEGES

The parameter secret is not valid. Only authorized clients can check the existence of a user

Conditions to decide the existence of an account

The account exists when:

  • The account indicated corresponds to a CASE or a PROFESSIONAL that has already initiated session before.

  • The account corresponds to a CASE or PROFESSIONAL that has never signed-in before (a PROFESSIONAL created by and administrator, or a CASE created by some PROFESSIONAL), but a default password has been assigned to the account. This means that the user should be able to sign-in using the default password

The account doesn’t exist when:

  • The account is not found (there is no contact in the platform with the provided account value)

  • The account exists internally but corresponds to a CASE or a PROFESSIONAL that has never initiated session before, and no default password has been assigned. This means that there is no way for the user to do a sign-in and it is necessary to follow the sign-up process to assign a new password. In this situation, the account_exists() function will indicate that the account doesn’t exist.

Conditions to allow the sign-up of a new account

Additionally, when the account corresponds to a user that has never done a sign-in, the account_exists() function will also indicate whether sign-up is permitted or not.

To allow sign-up, the holder of the account should have never signed-in before and additionally one of the following conditions must be met:

  • The account provided corresponds to a CASE (patient) that has been created in the platform by a PROFESSIONAL (the account exists internally), and without a default password (when a default password is assigned to the account, the system assumes that it will be notified to the CASE so that he can do a normal login).

  • The shared_key contains an explicit invitation to sign-up

  • The team provided has a default Program assigned with the “auto-enroll” property enabled.

  • The platform is configured with a default SUBSCRIPTION, and the TEAM OWNER of the SUBSCRIPTION has the “auto-enroll” property enabled (see the $GLOBALS['CASE_DEFAULT_SUBSCRIPTION'] configuration parameter in WEB SERVICES CONFIGURATION )

After the first successful sign-in of a user, the account_exists() function will never say again that the sign-up is allowed.

Related content