Custom Properties

The Fullstory API provides a way for clients to provide custom properties via a properties field. For example, here’s how clients can provide custom data in the properties field when creating users:

POST /v2/users

{
  "uid": "xyz123",
  "properties": {
    "pricing_plan": "paid",
    "popup_help": true,
    "total_spent": 14.50,
    "days_active": 2
  }
}

Events also support custom properties.

Values contained within custom properties can either be an array type, object type, or one of these primitive types:

• string
• real
• integer
• boolean

Dates are represented by strings that match the ISO-8601 format.

We support nested objects. We don’t currently support arrays of objects.

Type Inference

All field types will be inferred from the values in the properties collection, unless field types are explicitly declared. Fullstory will infer all Number types in request bodies as a real type. For example:

POST /v2/users

{
  "uid": "xyz123",
  "properties": {
    "pricing_plan": "paid", // this will be inferred as a string
    "popup_help": true, // this will be inferred as a boolean
    "total_spent": 14.50, // this will be inferred as a real
    "days_active": 2 // this will be inferred as a real
  }
}

Optional Type Declarations

Types can be explicitly declared for any field in the properties collection via an optional schema field. For example, if you wanted to ensure that the days_active property is an int, the type can be declared with a corresponding property type definition as part of schema field:

POST /v2/users

{
  "uid": "xyz123",
  "properties": {
    "pricing_plan": "paid",
    "popup_help": true,
    "total_spent": 14.50,
    "days_active": 2
  },
  "schema": {
    "properties": {
       "days_active": "int"
    }
  }
}

This will ensure that Fullstory converts the “days_active” field to an integer for analysis.

Nested types support type declarations as well using a flattened path selector (like location.code):

POST /v2/users

{
  "uid": "xyz123",
  "properties": {
    "pricing_plan": "paid",
    "popup_help": true,
    "total_spent": 14.50,
    "days_active": 2,
    "location": {
      "code": 404,
      "city": "Atlanta"
    }
  },
  "schema": {
    "properties": {
       "days_active": "int",
       "location.code": "int"
    }
  }
}

Types are defined using the following pattern:

"schema": {
  "properties": {
    "<property path>": "<type>"
  }
}

These are the types that can be declared and their declaration values:

Type	Declaration Value
boolean	"bool"
date	"date"
integer	"int"
real	"real"
string	"str"
array of boolean values	"bools"
array of integer values	"ints"
array of date values	"dates"
array of real values	"reals"
array of string values	"strs"

Type Conflicts

Clients may modify a property type definition over time. This will result in a single property being defined with multiple types. When this occurs, Fullstory will return the latest values with related type annotations for each property that has been captured with multiple types in a type_conflicts field.

Let’s say you created a user at time X:

POST /v2/users

{
  "uid": "xyz123",
  "properties": {
    "days_active": 2 // this will be inferred as a real
  }
}

And then updated the user at time Y:

POST /v2/users

{
  "uid": "xyz123",
  "properties": {
    "days_active": 3
  },
  "schema": {
    "properties": {
       "days_active": "int"
    }
  }
}

When fetching data for this user, you’ll receive a type_conflicts field that contains the two values and their related types. The property that is in conflict will be null:

GET /v2/users?uid=xyz123

{
  "id": "123456789"
  "uid": "xyz123",
  "properties": {
    "days_active": null
  },
  "type_conflicts": {
    "properties": {
      "days_active": {
        "real": 2.00,
        "int": 3
      }
    }
  }
}

Property Requirements

• Property names can only contain a sequence of alphanumeric characters A-Z, a-z, or 0-9 and underscores ("_").
• The maximum property name length is 512 characters. For properties that have nested object values, the property name including the dotted concatenation of all its parent properties must still be under the length limit of 512 characters.
• Properties have a maximum value size of 8192 bytes.

Property Cardinality Limiting

There is an organization-wide limit on the total number of user variables, event names, and event properties that Fullstory will accept. These limits are as follows:

• Up to 500 unique custom properties from POST /users
• Up to 1,000 unique event names from POST /events
• Up to 5,000 unique custom properties from POST /events

Here's a few other things to keep in mind when it comes to these cardinality limits:

• A given property name can be sent any number of times and will only count once toward the cardinality limit.
• Properties with the same name sent with POST /users and POST /events are considered different properties for the cardinality limit.
• Properties with the same property name but different event names in POST /events are considered different properties for the cardinality limit.

If the cardinality limit is reached for either POST /events or POST /users, new property names will be rejected and will not be captured by Fullstory, and no new property names will be accepted. This limit will slowly reset as property names become older than the product analytics retention window. While we will still show new events in the event list in session replay, they cannot be indexed or made searchable due to the cardinality limit.

If your organization accidentally exceeded the cardinality limit and need it more quickly, contact us at support@fullstory.com.