User Profiles

Users are one of the entities tracked by Moesif. A user is an end-user of your application. If you are an API provider, this may be your immediate customers or 3rd party developers consuming your API. If your serving a partner API, your users are your partners.

On the other hand if you are developing a mobile or web app, your end-users may be the end consumers of that app.

What are user properties?

Users can track various properties such as email, first_name, last_name, etc. For a full list of properties, checkout the User API Reference

Identification of users

Users in Moesif are identified by two attributes: user_id and session_token.

  • A user_id is a permanent and unique identifier to track a user across platforms and services. It is recommended to set the Moesif user_id field with the id used in your own databases and services.

  • A session_token may be temporary or can expire unlike a user_id. Examples include JSON Web Tokens’s (JWT), API keys, and session ids.

How to create and update users

Create and update users are available via the same update user API. If you attempt to update a user and the user_id doesn’t exist, a new user will be created (i.e. upsert). The update user API is accessible through the Moesif API Libs. Follow the installation instructions for your language.

A typical server integration will use two Moesif components:

  1. Server middleware SDK such as moesif-servlet to log the API call automatically to Moesif.
  2. API Lib such as moesifapi-java to perform any CRUD operation on the Moesif API such as updating a user.

How to alias a session

Multiple sessions can be associated to the same user profile. That is, the same user_id will be linked to multiple session_token’s.

To create a new link or alias, call the update user API with at least the user_id and session_token set. The new session_token will be appended to the existing user’s alias table.

For example, if you authorize a user by a JSON web token that expires after two weeks,

User metadata

You can save any custom metadata with a user such as the user’s email or a company_id. You can search and filter by users in the Moesif portal via the metadata. The metadata must be a valid JSON object.

  "is_email_verified": true,
  "facebook_id": "123456789",
  "email": "",
  "phone": "123-456-7890",
  "billing_date": 1516909500000,
  "first_name": "Amy",
  "last_name": "Doe",
  "custom_int_field": 55,
  "custom_obj_field": {
    "sub_a": "value_a",
    "sub_b": "value_b"

The user metadata can be views in Moesif under a user’s profile. You can also filter and segment by fields set in the user metadata.

API Search views

The same rules that apply to API Event metadata also apply to user metadata.

1. Maintain consistent datatypes

Once a JSON key is seen by Moesif with a specific JSON datatype, you cannot send a different JSON datatype using the same key. For example, if you previously sent to Moesif the following custom metadata for an API call:

  "first_name": "John Doe",
  "email": "",
  "phone": "123-456-7890"

Then, Moesif automatically saves phone as a JSON string in the metadata schema. You cannot later send a JSON Number using the same phone key. This is true regardless of the number of levels relative to the object root. The below metadata would now be invalid:

  "first_name": "John Doe",
  "email": "",
  "additional_info": {
    "phone": 1234567890

The metadata schema is shared across your organization and applications.

2. Avoid dots characters

Be aware that Dot characters in a JSON key for custom metadata will be converted into an underscore by Moesif automatically. Hoever, Dot characters in a JSON value are fine and will not be transformed.

For example,

  "": "John Doe",
  "email": "",

Will be converted by Moesif to:

  "fi_rst_na_me": "John Doe",
  "email": "",


Leave a comment