Document Categories

Tracking Users

Usermost offers APIs for creating and updating users. Both of these operations can be performed using the /usersendpoint as described below.

Identifying users

There are two types of user identifiers that Usermost uses:

  1. Anonymous IDs (deviceId) for users who are unidentified
  2. Non-anonymous IDs (userId) for users who are identified

Assigning a userId helps collect the user’s activity and information across systems in a single unified profile.

A user profile’s ID once assigned, cannot be changed. Although ID can be any Stringthat uniquely identifies users in your system, we recommend using system generated user IDs from your database instead of information that can change over time such as email addresses, usernames or phone numbers.

The usual places to assign IDs are

  • On user signups
  • On user logins
  • On screen or page views where user identity becomes known
  • When the user context changes

You can assign device ID by passing “deviceId” and user ID by passing “userId” parameter in the request body.

User attributes

There is often additional identifying information, such as name and email address, associated with user profiles. You can set these attributes using respective parameters in the request body as described below. These attributes can be used to segment users and target campaigns to a specific group. Additionally, they can be referred to personalize campaign messages to each user.

Attributes can be set on “anonymous” profiles as well.

Each user session has its own user attributes, but they get copied from one session to the next. This is in contrast to event parameters, which may take on different values per event. For this reason, you generally use user attributes for things that do not change much within the session, or with which you want the entire session associated.

Setting system attributes

You can set system attributes by passing them as parameters in the request body as described below.

There are two types of passing users to Usermost:

  1. Sending each user in separate requests (/users)
  2. Sending a list of users in batch request (/usersBatch)

METHOD:
POST

DESCRIPTION:
Add or update users.

URL STRUCTURE:

<HOST>/v1/accounts/<YOUR_USERMOST_LICENSE_CODE>/users

<HOST>/v1/accounts/<YOUR_USERMOST_LICENSE_CODE>/usersBatch

HEADERS:

NameDescription
x-request-id:{HEX_STRING}Replace {HEX_STRING}with a unique random hex string.If API re-attempts are being made, this tag stops propagation of duplicate events within a 4 hour window. Events with same ID re-attempted within 4 hours won’t get duplicated if the previous HTTPrequest was able to ingest the event.

EXAMPLE:

Sending a user in a request:

curl -X POST <HOST>/v1/accounts/<YOUR_USERMOST_LICENSE_CODE>/users \
    –header 'Authorization: Bearer <YOUR_API_KEY>' \
    –header 'Content-Type: application/json' \
    –data '{
				"userId": "16135550138",
				"firstName": "John",
				"lastName": "Smith",
				"birthDate": "1980-11-11T00:00:00+0000",
				"gender": "male",
				"email": "[email protected]",
				"phone": "+16135550138",
				"currentPoints": "11",
				"pushKey": "pwj398ft1039d84529",
                                "attributes": {
                                      "field1":"value1",
                                      "field2":123.4,
                                      "field3":"1988-11-11T00:00:00+0000",
                                      "field4":true
                                }
	}'

Sending a batch of users in a request:

curl -X POST <HOST>/v1/accounts/<YOUR_USERMOST_LICENSE_CODE>/usersBatch \
    –header 'Authorization: Bearer <YOUR_API_KEY>' \
    –header 'Content-Type: application/json' \
    –data '{
	"list": [
			{
				"userId": "16135550138",
				"firstName": "John",
				"lastName": "Smith",
				"birthDate": "1980-11-11T00:00:00+0000",
				"gender": "male",
				"email": "[email protected]",
				"phone": "+16135550138",
				"currentPoints": "10",
				"pushKey": "pwj398ft1039d84529",
                                "attributes": {
                                      "field1":"value1",
                                      "field2":123.4,
                                      "field3":"1988-11-11T00:00:00+0000",
                                      "field4":true
                                }
			},
			{
				"userId": "16135550139",
				"firstName": "Tom",
				"lastName": "Smith",
				"birthDate": "1980-11-11T00:00:00+0000",
				"gender": "male",
				"email": "[email protected]",
				"phone": "+16135550138",
				"currentPoints": "11",
				"pushKey": "pwj398ft1039d845886",
                                "attributes": {
                                      "field1":"value1",
                                      "field2":123.4,
                                      "field3":"1988-11-11T00:00:00+0000",
                                      "field4":true
                                }
			}
	]
	}'

PARAMETERS:

Sending a user in a request:

{
	"userId": "16135550138",
	"firstName": "John",
	"lastName": "Smith",
	"birthDate": "1980-11-11T00:00:00+0000",
	"gender": "male",
	"email": "[email protected]",
	"phone": "+16135550138",
	"currentPoints": "11",
	"pushKey": "pwj398ft1039d84529",
        "attributes": {
             "field1":"value1",
             "field2":123.4,
             "field3":"1988-11-11T00:00:00+0000",
             "field4":true
        }
}

Sending a batch of users in a request:

{
	"list":	[
		{
			"userId": "16135550138",
			"firstName": "John",
			"lastName": "Smith",
			"birthDate": "1980-11-11T00:00:00+0000",
			"gender": "male",
			"email": "[email protected]",
			"phone": "+16135550138",
			"currentPoints": "10",
			"pushKey": "pwj398ft1039d84529",
                        "attributes": {
                               "field1":"value1",
                               "field2":123.4,
                               "field3":"1988-11-11T00:00:00+0000",
                               "field4":true
                        }
		},
		{
			"userId": "16135550139",
			"firstName": "Tom",
			"lastName": "Smith",
			"birthDate": "1980-11-11T00:00:00+0000",
			"gender": "male",
			"email": "[email protected]",
			"phone": "+16135550138",
			"currentPoints": "11",
			"pushKey": "pwj398ft1039d845886",
                        "attributes": {
                               "field1":"value1",
                               "field2":123.4,
                               "field3":"1988-11-11T00:00:00+0000",
                               "field4":true
                        }
		}
	]
}

Constraints:

● Maximum size of user list in batch request can be 100.

ParameterTypeDescriptionIs mandatory
userIdStringIdentifier for known user.
userId is mandatory. User ID can be found on the respective user’s profile screen on Usermost dashboard.
Constraint:
● userIdcan be of maximum 100 characters.
 
No
deviceIdStringIdentifier for anonymous user. Either one of userIdor deviceId is mandatory. In case both IDs are sent, deviceId will be ignored. User ID can be found on the respective user’s profile screen on Usermost dashboard.
Constraint:
● deviceId can be of maximum 100 characters.
 
No
firstNameStringFirst name of the user.No
lastNameStringLast name of the user.No
birthDateDateBirth date of the user in ISO format: yyyy-MM-ddTHH:mm:ss±hhmm.No
genderStringGender of the user.
Can be one of male, femaleor other.
No
emailStringEmail address of the user.No
phoneStringPhone number of the user.
phonemust be in E.164 format, eg. +16135550138.
No
currentPointsIntegerCurrent points of the userNo
pushKeyStringThe FCM push key of the userNo
webPushKeyStringThe web SDK push key of the userNo
pushPackageNameStringThe package name that set on FCM for the userNo
cityStringThe city of the userNo
stateStringThe state of the userNo
countryStringThe country of the userNo
deviceTypeStringThe type of device of the user. This field can be one of “web”, “android” or “ios”No
mobileCarrierStringThe mobile carrier of the user’s deviceNo
deviceBrandStringThe brand of user’s deviceNo
registrationTimeDateRegistration time of the userNo
attributesJSONThe JSON object to send custom attributesNo

RETURNS:

{	
	"response": {
		"status": "queued"
	}
}

ERRORS:

Example: userId missing

{
	"response": {
		"message": "Error: userId and anonymousId cannot be empty.",
		"status": "error"
	}
}

Custom Attributes:

Custom Attributes are specific user data that you can custom define and track for all your users. These enable you to understand a user’s preferences in the context of your business and deliver contextually personalized experiences in real-time.

Depending on your business, these attributes could be anything like:

  • RFM Score | Lead Score
  • Language
  • Membership Type | Membership Status | Subscription Status
  • Trial Start Date | Trial End Date | Trial Days
  • Country Code
  • Preferred Genre
  • Offer Type and so on.

Setting Attribute Values

You can use “attribute” field in your JSON object to set the value of Custom Attributes for each user. This enables you to segment users and deliver contextually personalized messages through all the channels of engagement.

Here are a few guidelines to help you create and track Custom User Attributes:

  • Custom User Attribute names are case sensitive and must be less than 50 characters long. String attribute values must be less than 1000 characters long. Any characters beyond that will be truncated.
  • Values of attributes can be one of BooleanNumberString and Date. You can create a maximum of 25 Custom User Attributes of each data type.
  • Custom User Attribute names must not start with um_. Names starting with um_ are reserved exclusively for internal use at Usermost. Thus, to avoid data contamination for your account, such data will be ignored if used for your attributes.

656 reads

Table of Contents

Let’s schedule your personalized demo