session_init (user, password, [IP], [host], [language], [APIVersion], [norewrite], [current_date], [calendar], [device], [extra])

ALL

SOAP, REST

Input parameters

• user: One of the following:

  • username

  • email

  • phone number: When using a phone number it is necessary to include the country prefix unless the country_code property is included in the extra parameter (see below)

  • Any unique IDENTIFIER of the user.

  • An employee reference if the user is logging with an internal ID of a particular company. An employee reference is internally stored as a TEAM IDENTIFIER, because it may happen that different companies share equal employee references (i.e. the employee reference is not a globally unique value that identifies a person). This user value can be provided in 2 ways:

    • As a plain employee reference (e.g. 12726): This is only allowed when the company property is included in the extra parameter (see below). Otherwise it would not be possible to determine the identity of the user since the employee reference may be equal in several companies.

    • As a concatenation of the employee reference and the company ID with the format employee_ref@company_id (e.g. 12726@LINKCARE). In this case it is not necessary to indicate the company property is included in the extra parameter because the company reference can be inferred from the user value.

• password: The password of the user. Alternatively it is possible to use a password generated by a Single Sign On mechanism as described in section Single Sign On Mechanism.

• IP: IP of the caller (the one who invokes this web service). If IP="", the system will try to determine automatically the remote connection IP

• host: Indicates the platform where the client application is running. Possible values are:

  • "web": The client application is a web browser. This is the default value if nothing is specified

  • "mobile_app": The client application is a mobile app

  • "desktop_app": The client application is a desktop application

• language: Preferred language code in 2-letter ISO format used (e.g. "en")

• APIVersion: API version compatibility mode. This value is used to use API functions as they were defined in the specified version. Note that indicating an older API version must be understood as working with the current version in a 'compatible mode'. The API works always with the last version and all functionalities are available, but you can continue invoking API functions as they were defined in the old version.
  If no value provided, a default compatibility mode will be assigned depending on the communication mode used to invoke the API:

  • When using the SOAP interface, the default API version is 0.0.0

  • When using the REST interface, the default API version is 2.7.25, since this is the first version where the REST interface was introduced

• norewrite: If is set than don't rewrite previous session for the same user

• current_date: This parameter is used to calculate the current timezone of the user. It is possible to indicate one of the following values:

  • (empty): Assume that the user is in the same timezone than the default system timezone

  • Current local datetime with format “YYYY-MM-DD hh:mm:ss”. The timezone assigned to the user will be an integer value calculated as the difference of the datetime provided and the UTC time. This option is not optimal since it is not possible to take into account the Daylight Saving Times when the system needs to calculate any date related to the user.

  • Regional timezone expression (e.g. “Europe/Madrid”). This option is available since API Version 2.7.32

• calendar: Not used.

• device: An unique and immutable ID for the device

• extra: Optional JSON string with information about the client application and Operative System:

  • ws_endpoint: (optional) endpoint that indicates to WS where it is located

  • shared_key:  (optional) an encrypted string that contains information about additional actions that should be executed after a successful session init (see SHARED KEY OBJECT).

  • push_token: (optional) a token that identifies the client to send Push Notifications.

  • country_code: Optional 2-letter ISO country code indicating the country of the user. This is necessary if the user 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.24

  • company: Used when the user can login using an employee reference of a particular company. The company value must be the TEAM CODE of the TEAM that represents the company. Introduced in API version 2.7.27

  • client: (optional) Information about the client OS and browser. Introduced in API version 2.7.15

    • os: name of the OS of the client: "Mac OS", "Windows", "Android", etc.

    • os_version: OS version number

    • browser: Name of the client web browser (if the client is a web browser): "Safari", "Chrome", "Firefox", etc.

    • browser_version: Version of the client web browser

    • app_name: Name of the Application (if the client is an APP)

Output Parameters

• token: The session ID, needed to call protected method

• user: The user ID (different from username), needed to call protected method

• language: Default/current language for the user

• role: Active ROLE of the user in this session

• team: Reference of the active TEAM in this session

• team_code: TEAM code of the active TEAM. Introduced in API version 2.7.20

• name: The name of the user

• image: id of image, to obtain image content user_get_image() must be called

• professional: The PROFESSIONAL ID if the user is a professional (is member of a team), otherwise null (empty)

• case: The CASE ID if the user is a professional (is member of a team), otherwise null (empty)

• associate: The ASSOCIATE ID if the user is an associate of one or more CASEs, otherwise null (empty)

• timezone: Time zone of the user (calculated based on the value of current_date)

• change_password_secret: SHARED KEY OBJECT generated only when the current password has expired. It is a string that can be used to invoke session_password_set() as the old password. The secret has an expiration date of 5 minutes. Available in API versions 2.7.9.1 and higher.

• 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

TIMEZONE.INVALID

The current_date provided does not seem to be valid. It does not correspond to a valid timezone (using as reference the current date/time in the server)

ACCOUNT.ACTIVATION_PENDING

The account already exists and the activation is pending. In this case, the shared key necessary to validate the account is also returned in the response

USER.LOCKED

Too many attempts to login with an invalid password. The account has been temporarily locked

USER.ATTEMPTS_LEFT

The password provided is not valid but there is still one or more chances to try again

USER.ACCESS_DENIED

Currently it is not possible to create new accounts 'from scratch'. It is necessary that the account has been pre-created by adding a CASE , USER or ASSOCIATE.

If the account indicated does not exist, the function returns this error

PASSWORD.EXPIRED

The password has expired and it is necessary to change it