Server Side User Properties

HTTP API - Sending server-side user properties to FullStory

User data often lives in many different systems across your organization. For example, perhaps you’re using a CDP, ERP, CRM, or marketing automation tool. With the Set User Properties API, you can pass user properties into FullStory on your schedule, not only when users are interacting with your properties. This allows you to integrate these platforms and gain a more complete view of your customer experience.

Using the API

In order to send server-side user properties to FullStory, the following conditions must be true:

  • The user must be identified in FullStory with a unique user ID (uid ), set using the FS.identify API
  • The system calling the Set User Properties API must know the user’s uid  

The Set User Properties Developer Documentation has more detailed information about how to use this API, but here's a sample request you can reference as an example. 

curl -X POST \{uid}/customvars \
  -H 'content-type: application/json' \
  -H 'Authorization: Basic {YOUR_API_KEY}'
  -d '{
    "displayName":"Daniel Falko",
    "email" : "",
    "pricingPlan_str" : "free",
    "popupHelp_bool" : true,
    "totalSpent_real" : 14.50

In the example above, 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, displayName is a system field, and setting it 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

The other fields, pricingPlan_str, popupHelp_bool, andtotalSpent_real are examples of hypothetical custom fields that 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.

Using custom user properties in FullStory

After you send custom user properties to FullStory, the properties will display on related user cards.


You can also search for user properties easily. Just look for the property name under “User Filters” when building your search.


To control which properties are available in Search, Admin or Architect users can archive custom user properties under Settings > Data Management > Properties


Note: You can configure up to 500 unique user properties.


Why would I use this API instead of FS.setUserVars?
The FS.setUserVars API is designed for sending client-side user properties to FullStory. Client-side user properties are present in the browser at the time the session is captured. On the other hand, this API allows you to send server-side user properties, or properties that aren’t available in the browser. This opens up more opportunity for integrating with behind-the-scenes systems across your organization. 

Does the user have to already exist in FullStory or will a request with a new ‘uid’ create a new user record?
The user must be previously-identified using the API.

Does this API support batch/bulk updates?
No, this first version of our API only supports updates to a single user at a time. However, multiple properties can be set for each user in a single request. We are considering adding a bulk API in the future.

Why am I seeing a ‘404 Not Found’ error in the response?
The user for which the API request is being made can not be found in the identified set of users within your FullStory organization. If you expect that user to already exist, please confirm by searching for that “User ID” within the FullStory application. Also, please double check that the uid in the API request’s URL is correct and that you are using an API key from the same organization.

Why am I receiving an ‘Invalid Argument’ error?
This is likely due to a missing or mismatched field type suffix. The custom user properties must conform to the custom API properties format outlined here.

Need to get in touch with us?

The FullStory Team awaits your every question.

Ask the Community Technical Support