Skip to main content
Version: v2

Getting Started

Once you've created an API Key, you're ready to start sending data to Fullstory.

Differences between V1 and V2​

The current API version (V2) is initially focused on enhanced data capture and processing.

Some features that will remain in the V1 API:

Migrating from V1 to V2​

Changes to custom properties​

The V2 API has significant changes to how custom properties for users and events are defined. Type suffixes are no longer required for custom properties. In fact, it is actually required that you omit these suffixes for all custom properties. Types will be inferred, but they can be declared explicitly by using the optional schema. See Custom Properties for more details.

Examples​

V1 user data updates require the addition of type suffixes on custom field names:

POST /users/v1/individual/{uid}/customvars

{
  "displayName": "Daniel Falko",
  "email": "daniel.falko@example.com",
  "pricingPlan_str": "free",
  "popupHelp_bool": true,
  "totalSpent_real": 14.55
}

It is required that you omit these suffixes for all custom properties for V2 user data create/update. Types will be inferred unless explicitly declared in a schema collection. All custom data is captured in a properties collection:

POST /v2/users

{
  "uid": "xyz123",
  "display_name": "Daniel Falko",
  "email": "daniel.falko@example.com",
  "properties": {
    "pricing_plan": "paid",
    "popup_help": true,
    "total_spent": 14.55
  }
}

Greater flexibility for user data​

  • In the V1 API, only users that have been identified during a browser or mobile app session can be updated via the Set User Properties endpoint. Otherwise, the API call will return a 404 "user not found" error.
  • The V2 API allows for user data creation and management for users that have not already been captured in a session. Anonymous users as well as identified users can be created/updated via the POST /v2/users and POST /v2/users/batch endpoints. Unlike the V1 API, a 404 error will not be returned if you send user data that hasn't already been captured in a session.
  • The V2 API returns a Fullstory-generated id field in case you wish to use it to reference user data in Fullstory. You can still provide a uid with the identifier that you already use in your system for any given user.

API Guarantees​

  • Over time, as an anonymous user is identified across multiple devices and via the server API, they will represent a single “logical” user.
  • A Fullstory-generated user id will remain stable and will be guaranteed to reference the same logical user after that user has been identified.
  • Once a user is identified, a different “id” value may be returned in the server API response of an operation on that user.
  • Once a user is identified, the state of their properties collection will represent the most recent state set for that user, even when property values were set when the user was anonymous, prior to being identified.
  • This means we will merge existing user properties with new properties being set, and resolve any collisions by taking the most recent value
  • Once a server API uid value has been set for a user (i.e. they’ve been identified), that value is immutable and any attempt to update the existing value will result in an error.

User Id Flow

Data Residency​

Fullstory uses Google Cloud Platform data centers to process and store data. The default data center for all customers is located in the US. As of August 2022, Fullstory also has a data center in the European Union (“EU”). Customers now have the option to designate the location of the data center that supports their Fullstory account.

All API requests use the api.fullstory.com domain. They are automatically routed to the correct data center based on what is configured for your Fullstory account. You can determine which data center your account is associated with in one of two ways:

  • The Fullstory URL you use to login
  • The API key you are using for API authentication. The data center used is included as the first three characters of the API key. If your API key was created prior to August 2022, it may not include this prefix. In this case, your API key will be associated with the na1 data center.
    • API key format: <data center>.<token>

Additional Information​