API - Capturing custom user properties

Please see Fullstory's developer documentation for more detailed API information:

Anytime you want to capture custom user properties or integrate with external tools (such as help desk software) call the Fullstory API.

The properties displayName and email are examples of system fields. A system field is a built-in field that Fullstory can use in special ways. For example, setting displayName will give each user a distinct display name in the Fullstory UI that can also be used in search.

System Field


What it does

uid string

Explicitly sets the unique identifier for the user

displayName string

Displays clear & distinct user names

email string

Displays user's email address

Other hypothetical custom fields such as, pricing_plan, popup_help, and total_spent are examples of things you could capture and later leverage in a search to find sessions of users with specific characteristics.

For example, using the custom fields above, you could answer questions such as:

  • Why haven't certain freemium users made in-app purchases?
  • How many freemium users have spent more than $10.50 on in-app purchases?
  • Who leaves pop-up help turned on most often: free, basic, or pro users?

Suffice it to say, custom user fields are pretty powerful.

User Properties in Action

When a user property is set, it will be preserved on a user until it is changed. The current value of a user property will be attached to every event (click, activity, custom event) as it happens. The value of the user property will be preserved for that event to be the actual value set at the time the event occurred. Changes to a user property will not effect previous events. Fullstory does not go back and change the values associated with previous events.

Example Scenarios:

Example 1: You are searching for the exact session where users signed up for something (ie. loyalty rewards, membership, plan type, etc.)

For this example, let's say we are passing a user variable for signup_status with two options: none or standard. If you just filtered on users with a standard sign-up status, you would see sessions from all of your signed up users, but not the exact session when they signed up. If you just filtered on users that clicked sign-up, you may get some false positives of existing members that clicked that button again for some reason.

However, if you set your user filter to signup_status is standard and then add an event filter of Clicked text is sign-up when the signup_status is none, you'll find the exact session when the user went from not signed up to signed up. Fullstory will pull sessions of existing signed-up users who performed the specific event when they weren't signed-up. The value here is that the user variable is preserved with the event.


Example 2: You are searching for the first purchase session for your top spenders.

For this example, let's say we are passing a user variable of lifetimeSpend. You can start your search using a user filter of lifetimeSpend is greater than $5K (for example) and an event filter of Clicked text is purchase when the lifetimeSpend is 0. Fullstory will pull existing users who have spent above $5K before and then will show the exact session where they clicked purchase when they hadn't spent anything at the time of that specific event.


Need to get in touch with us?

The Fullstory Team awaits your every question.

Ask the Community Technical Support