The FullStory Server API is a RESTful API that enables developers to programmatically send user and event data to FullStory. It supports creating and updating individual users, batch importing users, sending server-side events, and batch importing events. The API uses JSON for request and response bodies and authenticates via API keys. Developers can use it to enrich FullStory session data with server-side context that is not available in the browser or mobile app.
openapi: 3.1.0
info:
title: FullStory Server API
description: >-
The FullStory Server API is a RESTful API that enables developers to
programmatically send user and event data to FullStory. It supports
creating and updating individual users, batch importing users, sending
server-side events, and batch importing events. The API uses JSON for
request and response bodies and authenticates via API keys. Developers
can use it to enrich FullStory session data with server-side context
that is not available in the browser or mobile app.
version: '2.0'
contact:
name: FullStory Support
url: https://help.fullstory.com/
termsOfService: https://www.fullstory.com/legal/terms-and-conditions/
externalDocs:
description: FullStory Server API Documentation
url: https://developer.fullstory.com/server/getting-started/
servers:
- url: https://api.fullstory.com
description: FullStory Production API Server
tags:
- name: Batch Import
description: >-
Import large volumes of users and events asynchronously using batch
import jobs that support up to 50,000 records per request.
- name: Events
description: >-
Send custom server-side events to FullStory. Events can be associated
with sessions and users, and include custom properties for behavioral
analysis.
- name: Users
description: >-
Create, retrieve, update, and delete users in FullStory. Users can be
anonymous or identified with a uid. Custom properties can be attached
to enrich user profiles.
security:
- basicAuth: []
paths:
/v2/users:
post:
operationId: createUser
summary: Create or update a user
description: >-
Creates a new user or updates an existing user if a matching uid is
found. Anonymous users can be created by omitting the uid field.
The API returns the FullStory-assigned id along with the user data.
Type suffixes are not required for custom properties in v2 as types
are inferred automatically.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'200':
description: User created or updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Invalid input provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
headers:
X-RateLimit-Remaining:
description: Number of requests remaining in the current window
schema:
type: integer
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: deleteUser
summary: Delete a user
description: >-
Permanently deletes all user data related to the specified user,
including sessions, events, custom user properties, raw page files,
and corresponding session data. It is recommended to use the Get
User endpoint first to verify the correct user before deletion.
tags:
- Users
parameters:
- $ref: '#/components/parameters/UidQuery'
responses:
'200':
description: User deleted successfully
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: User not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v2/users/{id}:
get:
operationId: getUser
summary: Retrieve a user
description: >-
Retrieves details for a single user by their FullStory-assigned user
ID. Returns user profile information including uid, display name,
email, custom properties, and the FullStory app URL for the user.
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserIdPath'
responses:
'200':
description: User retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: User not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v2/users/batch:
post:
operationId: createBatchUserImport
summary: Create a batch user import job
description: >-
Imports up to 50,000 users in a single asynchronous request. Returns
a job object with an ID and status that can be polled for completion.
Users can be anonymous or identified with a uid.
tags:
- Batch Import
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUserImportRequest'
responses:
'200':
description: Batch import job created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BatchJob'
'400':
description: Invalid input provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v2/events:
post:
operationId: createEvent
summary: Create a single event
description: >-
Creates one custom event with the specified details. Events can be
associated with a session and user. If use_most_recent is true, the
most recent session within 30 minutes will be used. Custom properties
can be attached and types are inferred automatically in v2.
tags:
- Events
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEventRequest'
responses:
'200':
description: Event created successfully
'400':
description: Invalid input provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v2/events/batch:
post:
operationId: createBatchEventsImport
summary: Create a batch events import job
description: >-
Imports a large number of events in a single asynchronous request.
Returns a job object with an ID and status that can be polled for
completion. Each event in the batch can include custom properties
and session associations.
tags:
- Batch Import
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchEventsImportRequest'
responses:
'200':
description: Batch events import job created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BatchJob'
'400':
description: Invalid input provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
API key passed in the Authorization header using Basic authentication.
Generate API keys from the FullStory app settings. Admin or Architect
level keys are required for data retrieval and deletion operations.
parameters:
UserIdPath:
name: id
in: path
required: true
description: >-
The FullStory-assigned user ID
schema:
type: string
UidQuery:
name: uid
in: query
required: true
description: >-
The external user identifier used to identify the user to delete
schema:
type: string
schemas:
CreateUserRequest:
type: object
description: >-
Request body for creating or updating a user in FullStory
properties:
uid:
type: string
description: >-
External user identifier. Omit to create an anonymous user.
display_name:
type: string
description: >-
The display name for the user
email:
type: string
format: email
description: >-
The email address for the user
properties:
type: object
description: >-
Custom key-value properties to attach to the user. Type suffixes
are not required in v2 as types are inferred automatically.
additionalProperties: true
schema:
type: object
description: >-
Optional explicit type declarations for custom properties to
override the default type inference
additionalProperties: true
User:
type: object
description: >-
A FullStory user object with profile information and custom properties
properties:
id:
type: string
description: >-
The FullStory-assigned unique identifier for the user
uid:
type: string
description: >-
The external user identifier provided during creation
display_name:
type: string
description: >-
The display name for the user
email:
type: string
format: email
description: >-
The email address for the user
properties:
type: object
description: >-
Custom properties attached to the user
additionalProperties: true
schema:
type: object
description: >-
Explicit type declarations for custom properties
additionalProperties: true
type_conflicts:
type: object
description: >-
Any type conflicts detected in custom properties
additionalProperties: true
app_url:
type: string
format: uri
description: >-
URL to view the user in the FullStory application
CreateEventRequest:
type: object
required:
- name
description: >-
Request body for creating a custom event in FullStory
properties:
name:
type: string
description: >-
The name of the custom event
timestamp:
type: string
format: date-time
description: >-
ISO 8601 timestamp for when the event occurred
session:
type: object
description: >-
Session association for the event
properties:
id:
type: string
description: >-
The session identifier to associate the event with
use_most_recent:
type: boolean
description: >-
If true, the most recent session within 30 minutes will be
used. If no recent session is found, the event is created
without a session association.
user:
type: object
description: >-
User association for the event. Not accepted if session.id is
provided since the session already identifies the user.
properties:
id:
type: string
description: >-
The FullStory-assigned user ID
uid:
type: string
description: >-
The external user identifier
properties:
type: object
description: >-
Custom key-value properties for the event. Supports string,
real, integer, boolean, array, and object types.
additionalProperties: true
schema:
type: object
description: >-
Optional explicit type declarations for custom event properties
additionalProperties: true
BatchUserImportRequest:
type: object
required:
- requests
description: >-
Request body for batch importing users into FullStory
properties:
requests:
type: array
description: >-
Array of user objects to import, up to 50,000 per request
maxItems: 50000
items:
$ref: '#/components/schemas/CreateUserRequest'
BatchEventsImportRequest:
type: object
required:
- requests
description: >-
Request body for batch importing events into FullStory
properties:
requests:
type: array
description: >-
Array of event objects to import
items:
$ref: '#/components/schemas/CreateEventRequest'
BatchJob:
type: object
description: >-
Represents an asynchronous batch import job
properties:
id:
type: string
description: >-
The unique identifier for the batch import job
status:
type: string
description: >-
Current status of the batch import job
enum:
- PENDING
- PROCESSING
- COMPLETED
- FAILED
created:
type: string
format: date-time
description: >-
Timestamp when the batch import job was accepted
Error:
type: object
description: >-
Standard error response from the FullStory API
properties:
code:
type: integer
description: >-
HTTP status code
message:
type: string
description: >-
Human-readable error message