Fullstory User Management API Guide

Auth method: API Key (Bearer token in Authorization header)

Setup steps

1. Log in to FullStory and navigate to Settings > Integrations > API Keys.
2. Click 'Create API Key', assign a name and select appropriate permissions (read, write).
3. Copy the generated API key; it is shown only once.
4. Include the key in all requests as: Authorization: Basic or as a Bearer token per the v2 docs.

Required scopes

Create or update user

• Method: POST
• URL: https://api.fullstory.com/v2/users
• Watch out for: This endpoint upserts: if the uid already exists, it updates the record rather than returning a conflict error.

Request example

POST /v2/users
Authorization: Basic <key>
Content-Type: application/json
{
  "uid": "user_123",
  "display_name": "Jane Doe",
  "email": "jane@example.com",
  "properties": {"plan_str": "enterprise"}
}

Response example

HTTP 200
{
  "id": "user_123",
  "display_name": "Jane Doe",
  "email": "jane@example.com",
  "properties": {"plan_str": "enterprise"}
}

Get user by ID

• Method: GET
• URL: https://api.fullstory.com/v2/users/{id}
• Watch out for: The {id} path parameter is your application's uid, not an internal FullStory ID.

Request example

GET /v2/users/user_123
Authorization: Basic <key>

Response example

HTTP 200
{
  "id": "user_123",
  "display_name": "Jane Doe",
  "email": "jane@example.com",
  "properties": {"plan_str": "enterprise"}
}

Update user (partial)

• Method: POST
• URL: https://api.fullstory.com/v2/users/{id}
• Watch out for: v2 uses POST (not PATCH) for updates to an existing user by uid.

Request example

POST /v2/users/user_123
Authorization: Basic <key>
Content-Type: application/json
{
  "display_name": "Jane Smith",
  "properties": {"plan_str": "business"}
}

Response example

HTTP 200
{
  "id": "user_123",
  "display_name": "Jane Smith",
  "email": "jane@example.com",
  "properties": {"plan_str": "business"}
}

Delete user

• Method: DELETE
• URL: https://api.fullstory.com/v2/users/{id}
• Watch out for: Deletion removes the user's identity data but session recordings may be retained per data retention settings.

Request example

DELETE /v2/users/user_123
Authorization: Basic <key>

Response example

HTTP 200
{}

List users (batch export / search)

• Method: POST
• URL: https://api.fullstory.com/v2/exports/users
• Watch out for: User listing is asynchronous via the Data Export API, not a synchronous paginated list endpoint. Poll for export completion before downloading results.

Request example

POST /v2/exports/users
Authorization: Basic <key>
Content-Type: application/json
{
  "type": "TYPE_EXPORT_USERS"
}

Response example

HTTP 200
{
  "exportId": "abc123",
  "status": "PENDING"
}

• Rate limits: FullStory v2 API enforces per-organization rate limits. Limits vary by endpoint category. Exceeding limits returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After on 429 responses. Exact per-endpoint limits are documented at developer.fullstory.com/server/v2/rate-limits/.
• Pagination method: token
• Default page size: 100
• Max page size: 1000
• Pagination pointer: page_token

• Webhooks available: No
• Webhook notes: FullStory does not expose user-management-specific webhooks. Event-driven integrations for user data are not documented in official sources.
• Alternative event strategy: Use the Data Export API (v2/exports) to pull user and event data on a scheduled basis.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.fullstory.com/scim/v2

• Supported operations: Create user (POST /Users), Get user (GET /Users/{id}), Update user (PUT /Users/{id}), Deactivate/delete user (DELETE /Users/{id}), List users (GET /Users), Push groups (GET /Groups, POST /Groups, PUT /Groups/{id})

Limitations:

• Requires SAML 2.0 SSO to be configured before SCIM can be enabled.
• SCIM provisioning is documented primarily via Okta custom SAML app integration; other IdPs (Entra, OneLogin) may require manual SCIM URL/token configuration.
• Enterprise plan required; not available on Business or lower tiers.
• SCIM token is generated in FullStory Settings > SSO & Provisioning and must be stored securely - shown only once.
• Group push maps to FullStory roles/permissions; role mapping must be configured in the IdP.

Three integration patterns are well-supported by the v2 API. For identity graph population, POST to /v2/users with uid, email, display_name, and typed custom properties (e.

g. , plan_str, account_id_str) - the endpoint upserts silently on uid collision, so uid uniqueness must be enforced upstream.

For automated deprovisioning, configure SCIM in Okta using base URL https://api.fullstory.com/scim/v2 and a one-time bearer token generated in Settings > SSO & Provisioning; Okta push then maps group membership to FullStory roles via SCIM DELETE /Users/{id} on unassignment.

For user audit exports, POST to /v2/exports/users to initiate an async job, poll GET /v2/exports/{exportId} until status is COMPLETE, then download and parse the result - this is not a synchronous paginated endpoint and polling latency must be accounted for in any sync workflow.

Provision a new user and set custom attributes

1. Generate an API key in FullStory Settings > Integrations > API Keys with write:users permission.
2. POST to https://api.fullstory.com/v2/users with uid, email, display_name, and any typed custom properties (e.g., plan_str, account_id_str).
3. Verify the 200 response contains the user object with properties reflected.
4. Optionally confirm in the FullStory UI under People that the user appears with correct attributes.

Watch out for: If the uid already exists, the POST silently upserts - ensure uid uniqueness in your system to avoid unintended overwrites.

Automate user deprovisioning via SCIM with Okta

1. Confirm Enterprise plan and SAML SSO are active in FullStory Settings > SSO & Provisioning.
2. Generate a SCIM bearer token in FullStory (shown once - store securely).
3. In Okta, add FullStory as a custom SAML app and configure SCIM: set base URL to https://api.fullstory.com/scim/v2 and paste the bearer token.
4. Enable 'Push Users' and 'Push Groups' in Okta provisioning settings.
5. Assign/unassign users in Okta; FullStory will activate or deactivate accounts automatically via SCIM DELETE /Users/{id}.

Watch out for: SCIM token is displayed only once at generation time. If lost, a new token must be generated and reconfigured in the IdP.

Export user list for audit

1. POST to https://api.fullstory.com/v2/exports/users with type TYPE_EXPORT_USERS to initiate an async export job.
2. Poll GET https://api.fullstory.com/v2/exports/{exportId} until status is COMPLETE.
3. Download the export file from the returned URL.
4. Parse the export (JSON Lines or CSV per FullStory format) to enumerate all user records and their properties.

Watch out for: Export jobs are asynchronous and may take minutes for large datasets. Do not assume synchronous availability; implement polling with backoff.

Several non-obvious behaviors create integration risk. Custom user properties require typed key suffixes (_str, _int, _real, _bool, _date) to be indexed correctly in the UI; untyped keys are accepted by the API but may not surface in analytics.

The v2 update path uses POST (not PATCH) against /v2/users/{id}, which diverges from REST convention and can cause confusion when building identity graph sync pipelines. Deleting a user via DELETE /v2/users/{id} removes PII and identity data but does not immediately purge session recordings - data retention settings govern recording lifecycle independently.

Rate limits on write endpoints are capped at 1,000 requests per minute organization-wide; responses include X-RateLimit-Remaining and Retry-After headers on HTTP 429, so implement header-aware backoff rather than fixed retry intervals.

Finally, SCIM enablement will fail silently if SAML SSO is not already active - the dependency is strict and not always surfaced clearly in error responses.