Core - User

The base url for the APIs in this page is at:

/api/mobile/

A JSON file with OpenAPI data about all core-related mobile APIs can be downloaded here.

Login

Login is handled via the /v1/user/mobile-logon endpoint:

POST /v1/user/mobile-logon

Handles logon from a smartphone environment, registering session information

Status Codes

200 OK – Success

The object to pass to this API is like this:

{
  Username: "username@username",          // String (Required)
  Password: "thepassword",                // String (Required)
  SmBrand: "smartphone Brand",            // String
  SmModel: "smartphone Model",            // String
  OsName: "Smartphone OS Name",           // String
  OsVersion: "Smartphone OS Ver",         // String
  AppName: "App Name",                    // String
  AppVersion: "App Version"               // String
}

All fields apart the Username and Password are optional, and are recorded together with session data for description and troubleshooting purposes.

The resulting object is like this:

{
  MustChangePassword: true                            // Boolean
  Token: "a valid JWT string",                        // String
  Roles: ["array","of","role","slugs"],               // String Array
  Name: "The registered first name of the user",      // String
  Surname: "The registered last name of the user",    // String
  FullName: "The registered full name of the user"    // String
}

The MustChangePassword field means that the user should be forced to change password The Roles and FullName fields may be used by the UI/UX to immediately hide/enhance the functions that may be accessed by the user.

In case of errors, the Message values that Movens may report are:

err_InvalidCredentials

When the credentials supplied cannot be matched to any registered user.

err_CannotAccess

The user has been successfully identified, but cannot access now.

This may be due to user having been blocked, not being confirmed (e.g. via a link in an e-mail message that must have been clicked), or not having enough roles to access the mobile endpoints.

err_TooManySessions

The user has reached the maximun allowed number of concurrent sessions

Logout

Logout is handled via the /v1/user/logoff endpoint:

POST /v1/user/logoff

Revoke a JWT for the current user

Status Codes

200 OK – Success

The API does not need any object provided, and it will logoff the current active session for the user.

Registration

The endpoint

POST /v1/user/register

Registers a new user on the platform.

Status Codes

200 OK – Success

can be used to register new users. The object to supply has this form:

{
  Email: "mail@address",                              // String
  MobilePhoneNumber: "123 4567890",                   // String
  Password: "chosenpassword",                         // String, minimum length 8 characters
  Community: "ABCDEFGHIJK",                           // String (Registration Code)
  Language: "en-US",                                  // String
  Name: "The User Name",                              // String
  Surname: "The User Surname",                        // String
  PrivacyAgreement: true,                             // Boolean
  TermsAndConditions: true                            // Boolean
}

Where only the Language field is optional, and will default to the invariant culture, that will produce English localization from the server.

A successful registration will produce the forwarding of an e-mail message to the user, to validate the new account, and will return a positive response without data.

The resulting object if the registration is successful is like this:

{
  Token: "a valid JWT string",                        // String
  Roles: ["array","of","role","slugs"],               // String Array
  FullName: "The registered full name of the user"    // String
}

The Roles and FullName fields may be used by the UI/UX to immediately hide/enhance the functions that may be accessed by the user.

Note: the JWT string issued by this endpoint cannot be renewed and will be invalidated upon expiration. User Agents should use it only to gather further information from the user and store it e.g. as custom fields, and should instruct the user to check the e-mail message and perform a login at the end of the registration workflow.

Should an error happen, the negative result will have one of these error messages:

err_AlreadyRegistered

Means that the e-mail address is already in use by an account that has been confirmed.

Note that this may lead to leaking information about an user existing.

err_InvalidCommunity

The supplied Guid for the community cannot be found as an active community in the system.

err_UnbelievableEmail

The supplied e-mail address is shorter than 3 characters, or does not contain an ‘@’ symbol, or does not contain at least one dot. This check is not RFC-5322 compliant, just to help prevent totally invalid strings.

err_InvalidPasswordLength

Password is rejected if shorter than 7 characters. UI/UX implementations should encourage longer and unique passwords on their own.

err_UnableToSendEmail

The system was not able to queue an e-mail message for delivery to the specified address.

err_NoPrivacyAgreement

No PrivacyAgreement or TermsAndConditions data has ben provided, or they have been set to false

err_InvalidUserdata

One or more mandatory additional user data was not provided or was invalid

Validate a user

Marks a user as validated during the registration procedure

GET /v1/user/validate/{userId}/{actionToken}

Marks a user as validated

Parameters

userId (string) – The GUID of the user to validate
actionToken (string) – The token value to check for validation

Status Codes

302 Found – Redirect

The request will redirect the user to a different destination on success/failure.

Unregister

The endpoint

POST /v1/user/unregister

Delete an user (Unregister a user)

Status Codes

200 OK – Success

can be user to revoke a user registration. The object to supply has this form:

{
  Username: "mail@address",     // String
  Password: "chosenpassword"    // String
}

Should an error happen, the negative result will have one of these error messages:

err_InvalidRequest: No username or password was provided
err_InvalidCredentials: The provided username and password does not match

Renew Token

Renew the token for the currently authenticated user:

POST /v1/user/token-renew

Creates a new JWT token from an existing one

Status Codes

200 OK – Success

If the request is successful it will return the new token.

If not a generic json error message will be returned.

Password Recovery

An user can request a password recovery simply specifying the username/e-mail address.

POST /v1/user/recover-password

Starts password recovery workflow for the given username

Status Codes

200 OK – Success

The format of the request object is this:

{
  Username: "email@address"
}

If the user exists and is available, the server will forward an e-mail message with a password reset link inside; the password reset form must be provided by the implementator and included inside the e-mail message template.

The errors that may happen are described by these messages:

err_InvalidRequest: The username is empty
err_UnableToSendEmail: The username may not exist, have been disabled, have an invalid e-mail address, or a temporary problem with e-mail delivery may have happened.

Password Reset

Completes the password recovery (reset) workflow for the given username, only if the token matches:

POST /v1/user/confirm/reset-password

Completes the password recovery (reset) workflow for the given username, only if the token matches

Status Codes

200 OK – Success

The format of the request object is this:

{
  Username: "username",                            // String
  Password: "password",                            // String
  Token: "a valid token"                           // String
}

The Token property has to be set with the action token provided in the password reset link sent by the password recover API. Possible errors are described by these messages:

err_InvalidRequest: Any of the required fields is empty or null, or the provided password is less than 8 characters
err_NoSuchUser: No user matching the username was found or an invalid token is provided
err_SamePassword: The new password provided is the same as the old one

Unsubscribe from community

Use this endpoint to unsubscribe the user from a community.

POST /v1/user/current/community-unsubscribe

Removes the user from the selected community

Status Codes

200 OK – Success

The object to supply has this form:

{
  Community: "753a5f64-70df-445d-97e2-43afc704a767",  // Guid
}

After successfully unsubscribing the user from the community, the API will return a new JWT token and invalidate the previous one:

{
  Token: "the new token"
}

The API will return a plain error message if problems occurred while removing the community (i.e. the provided community is the only one the customer is subscribed to), or one of the following:

err_InvalidCommunity: The provided guid does not map to any existing community the user is subscribed to

Get current user master data

Use this endpoint to retrieve the full master data object for the current user (i.e. the user owning the current Authorization token).

GET /v1/user/current

Describes the current user, and the communities they belong to

Status Codes

200 OK – Success

Response example:

{
  Name: "John",                                               // String
  Surname: "Doe",                                             // String
  FullName: "John Doe",                                       // String
  Roles: ["Role A","Role B"],                                 // String Array
  UserName: "user@email.com",                                 // String
  Email: "user@email.com",                                    // String
  MobilePhoneNumber: "0123456789",                            // String
  CreatedDate: "2001-01-01T01:01:01Z",                        // DateTime
  FCMTokens: ["b6486c40-c5a8-428c-a7be-995df0513dbe",..]      // String (nullable)
  LCID: 100,                                                  // Int
  Language: "en-US",                                          // String
  AvatarImage: "013d7d16d7ad4fefb61bd95b765c8ceb..."          // ByteArray as String (nullable)
  Communities:
  [
    {
       Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",          // Guid
       Name: "Community",                                     // String
       PrimaryColor: 123456,                                  // Int (nullable)
       AccentColor: 123456,                                   // Int (nullable)
       Logo: "AAAAAAAAAA==",                                  // ByteArray as String (nullable)
       Details:
       {
         Key: "detail-key",                                   // String
         Value: "value"                                       // String
       }
    },
    ...
  ],
  ActiveSessions: 4,                                          // Int, currently active sessions count
  IsDisabled: false,                                          // Boolean
  IsDisablesByAdmin: false,                                   // Boolean
  IsDisabledBySystem: false,                                  // Boolean
  OverriddenSystemDisableStatus: false,                       // Boolean
  SystemDisabledReasons: ["No payment data", ...],            // String array (nullable)
  Agreements: {
    TermsAndConditions: true,                                 // Boolean
    TermsAndConditionsDate: "2021-01-01T00:00:00Z",           // Datetime (nullable)
    PrivacyData: true,                                        // Boolean
    PrivacyDataDate: "2021-01-01T00:00:00Z"                   // Datetime (nullable)
  }
}

AvatarImage is a base64-encoded image.

FCMTokens is the array of identifiers for the FireBase channels in which the notification for the user are sent.

Community data includes a base64-encoded logo image, and primary/accent colors as integer values.

Get current user disabled status

Use this endpoint to retrieve the full master data object for the current user (i.e. the user owning the current Authorization token).

GET /v1/user/current/disabled-status

Returns data on the user disabled status

Status Codes

200 OK – Success

Response example:

{
  IsDisabled: false,                                          // Boolean
  IsDisabledByAdmin: false,                                   // Boolean
  IsDisabledBySystem: false,                                  // Boolean
  OverriddenSystemDisableStatus: false,                       // Boolean
  SystemDisabledReasons: ["No payment data", ...]             // String array (nullable)
}

Update current user data

POST /v1/user/current/full-name

Changes the full name for the current user

Status Codes

200 OK – Success

With a body like this:

{
  Name: "John",
  Surname, "Doe"
}

It will return a plain negative response if no name or surname has been provided.

POST /v1/user/current/avatar-profile

Changes the avatar image for the current user

Status Codes

200 OK – Success

With a body like this:

{
  Base64String: "base64-encoded content of the file"
}

POST /v1/user/current/password

Updates the password for the current user

Status Codes

200 OK – Success

With a body like this:

{
  Password: "newpassword"
}

The API will also renew the current token, and will return the new token value:

{
  Token: "a valid JWT string",    // String
}

Possible errors are:

err_SamePassword: The new password provided is the same as the old one
err_InvalidPasswordLength: The new password provided is shorter than the min accepted length of 8 characters

POST /v1/user/current/email

Updates the e-mail address for the current user

Status Codes

200 OK – Success

With a body like this:

{
  Email: "newmail@mail.com"
}

It will return a plain negative respose if no email has been provided.

Possible errors are:

err_SameEmailAddress: The new email address provided is the same as the old one

GET /v1/user/confirm/email

Completes the e-mail update workflow for the given username and token

Query Parameters

userguid (string) –
token (string) –

Status Codes

302 Found – Redirect

Completes the e-mail address modification process.

The API expects to receive both userguid and token in the query parameters.

If the guid matches an existing user and the token is valid, the user will be redirected to a URL.

Errors will return a 400 Bad Request response if no user has been found for the provided userguid, the provided token does not match to a valid token or no pending email address value is set for the provided user.

POST /v1/user/current/mobile

Updates the mobile phone number for the current user

Status Codes

200 OK – Success

With a body like this:

{
  MobilePhoneNumber: "9876543210"
}

It will return a plain negative response if no mobile phone number has been provided;

Possible errors are:

err_SameMobileNumber: The new mobile phone number provided is the same as the old one

GET /v1/user/confirm/mobile

Completes the mobile update workflow for the given username and token

Query Parameters

userguid (string) –
token (string) –

Status Codes

302 Found – Redirect

Completes the mobile phone number modification process.

The API expects to receive both userguid and token in the query parameters.

If the guid matches an existing user and the token is valid, the user will be redirected to a URL.

Errors will return a 400 Bad Request response if no user has been found for the provided userguid, the provided token does not match to a valid token or no pending mobile phone number value is set for the provided user.

POST /v1/user/current/language/{language}

Sets a new default language for the user

Parameters

language (string) – An ISO3166 culture code

Status Codes

200 OK – Success

If the request is successful, a positive response will be returned.

If there is a problem retrieving the current user, a negative Json response will be returned.

Other errors that may happen are described by these messages:

err_LanguageNotSet: No language was set in the query parameters
err_NoSuchCulture: A non valid (null) or not recognized ISO3166 culture code was provided by the request

All of these operations (unless otherwise specified) produce just a positive or negative response without any further indication.

When updating the e-mail address or the mobile phone number the server sends a message, via a system-defined channel, to the user with a link to visit to complete the update.

Update user agreements

POST /v1/user/current/agreements

Allows the user to set its agreements

Status Codes

200 OK – Success

With a body like this:

{
  TermsAndConditions: true    // Boolean
}

Edits the user’s agreement. Might return a generic error if no previous agreement data has been found on the user or if no TermsAndConditions property has been provided, or one of the following error messages:

err_CannotRemoveAgreement: The term and conditions agreement has already been given, and no update has been allowed

Add FCM token

POST /v1/user/current/fcm-token

Adds the provided FCM device token on the current user’s token list

Status Codes

200 OK – Success

DELETE /v1/user/current/fcm-token

Removes the provided FCM device token from the current user’s token list

Status Codes

200 OK – Success

With a body like this:

{
  FCMToken: "b6486c40-c5a8-428c-a7be-995df0513dbe"
}

Add a new FCM device token for the current user except when the token already exists. The API will return a plain positive Json response or a generic error if no token is provided or if an error occurs.

Delete FCM token

POST /v1/user/current/fcm-token

Adds the provided FCM device token on the current user’s token list

Status Codes

200 OK – Success

DELETE /v1/user/current/fcm-token

Removes the provided FCM device token from the current user’s token list

Status Codes

200 OK – Success

With a body like this:

{
  FCMToken: "b6486c40-c5a8-428c-a7be-995df0513dbe"
}

Remove a FCM device token for the current user. The API will return a plain positive Json response or a generic error if no token is provided or if an error occurs.

Remove current user

POST /v1/user/current/remove

Removes the current user from the system, with a self-deletion date. Anonymization will follow later.

Status Codes

200 OK – Success

With a body like this:

{
  Password: "actualpassword"
}

Only the Password property of the posted JSON object is read. For convenience, User Agents may post other data (i.e. serialize an entire User object).

User Agents should not send a stored user password but ask it upon starting the deletion procedure, to confirm the user’s intention.

Synchronize Custom Fields

Users may have customizable fields added to them. To synchronize them with the server, this endpoint can be used.

POST /v1/user/current/fields/sync

Synchronizes server-side field data with data from the client. Fields not mentioned in the body will not be updated.

Status Codes

200 OK – Success

With a body like this:

{
  Fields: [
    {
      Key: "fiscal-code",
      CurrentValue: "123ABC987XYZ"
    }
  ]
}

The server will receive and store the value of configured fields, and will return to the User Agent the list of all actual fields (and values), and the list of errors that arise while saving the data:

[
  Fields: [{
    Key: "fiscal-code",                       // String
    Labels: "{\"en\":\"Fiscal Code\"}",       // String
    DescriptionLabels: "",                    // String
    ValidValues: "",                          // String
    ValidValuesLabels: "",                    // String
    ValueType: 2,                             // Int
    IsRequired: true,                         // Boolean
    CurrentValue: "123ABC987XYZ"              // String
  }, ... ],
  Errors: [{
      Field: "Birth date",    // Localized field name
      Code: "10101",          // Numeric code of the error
      Message: "..."          // Localized description of the error
  }, { ... } ]
]

The error reason may be:

30000: the field is marked as required but no value has been provided
30001: the field value is not valid as per the related additional user data field settings

It may also return a plain error response if one of the provided fields has the Key property missing or empty.

The Labels property contains a JSON dictionary that must be separately parsed. In the dictionary there is the proper translation, for available IETF language tag, of the meaning of this filter.

In the ValidValuesLabels property there is a context-dependent JSON dictionary that must be separately parsed by the User Agent. In the dictionary, for each valid value, there is the proper translation, for available IETF language tags, of the meaning of such value.

Value types can be one of the AdditionalValueTypes enumeration.

Attachment fields have a CurrentValue of the attachment Guid; storing a new value requires using a different endpoint.

Storing an Attachment custom field

To store an Attachment-type custom field value, the User Agent must use this endpoint.

POST /v1/user/current/fields/attachment-field

Receives the value for an attachment-type field

Status Codes

200 OK – Success

With a request body like this:

{
  Key: "user-selfie",                 // String
  Data: "AAAAAAAAAAA==",              // String
  Name: "selfie1.jpg",                // String
  MimeType: "image/jpeg"              // String
}

Where in Data there is the Base64-encoded content of the file.

The server will receive the data, store it, and return a positive response upon success and a negative response if the file cannot be stored. Inside the Data field for the positive response there is the Guid referring to the stored attachment.

Get current user statistics

Use this endpoint to retrieve trip summary data for the current operator Number of trips, seconds of travel, km traveled

POST /v1/user/current/statistics

Gets the basic statistics of the current user

Status Codes

200 OK – Success

With a body like this:

{
  fromDate: "2012-04-23T18:25:43.511Z",       // DateTime (nullable)
  toDate: "2012-04-23T18:25:43.511Z"          // DateTime (nullable)
}

The API will automatically set both fromDate and toDate to have a max time span, as defined in the configuration variable MAX_STATISTICS_DAYS, with priority on the end date.

The API will respond with a plain error response if one or both the dates are in an invalid format or if toDate is inferior of fromDate, or with a positive response in the following format:

{
  TripCount:44,               // Int
  SecondsTraveled:17580,      // Int
  KmTraveld:100               // Int
}

Core - User

Login

Logout

Registration

Validate a user

Unregister

Renew Token

Password Recovery

Password Reset

Subscribe to community

Unsubscribe from community

Get current user master data

Get current user disabled status

Update current user data

Update user agreements

Add FCM token

Delete FCM token

Remove current user

Synchronize Custom Fields

Storing an Attachment custom field

Get current user statistics