User API Migration Guide

Learn how to migrate to the latest version of the User API endpoints.

Employee App
Staffbase Intranet

Staffbase has introduced new versions for several User API endpoints. These new versions offer improved performance and usability. Staffbase recommends migrating to these new versions to take advantage of the enhancements. The older versions will be deprecated in the future. Learn more about Staffbase API lifecycle.

This article explains:

  • The main differences between the old and new versions of the User API endpoints.
  • When to use the newly introduced endpoints, which are designed to replace certain legacy behaviors and deliver the same results more efficiently.

This article highlights only the main version differences. It does not include sample requests or responses. For detailed examples or information about each endpoint versions, refer to the User API specification.

POST request to /users, with the required Accept and Content-Type headers:

  • Accept header: application/vnd.staffbase.accessors.user.v3+json
  • Content-Type header: application/vnd.staffbase.accessors.user-invite.v2+json
  • Changes in request body:
    • Required fields:
      • role
      • locale
    • System profile field values are only part of the profile object
    • Removed fields (no longer returned in the response):
      • mandatoryGroupIDs
      • groupIDs
      • tags
      • inviteMessage
    • Restructured fields: recoveryCode is now an object
    • Renamed fields:
      • externalID to externalId
      • emails/primary to email

POST request to /users with only the required information and returns the full user object.

GET request to /users with required Accept header:

  • Accept header: application/vnd.staffbase.accessors.user.v3+json
  • Changes in request parameters:
    • Use cursor instead of offset for pagination.
    • Search-related query parameters are not supported. Instead use the /users/search endpoint.
    • Add the includeProfile query parameter to retrieve profile data
  • Removed fields (no longer returned in the response):
    • mandatoryGroupIDs
    • groupIDs
    • tags
    • inviteMessage
    • Restructured fields: recoveryCode is now an object
    • Renamed fields:
      • externalID to externalId
      • emails/primary to email

GET request to /users returns all user information according to the specified query parameters, but relies on the offset-based pagination, which is not performant for large datasets.

This is a newly introduced endpoint designed to replace the legacy GET request for returning all users. The search endpoint provides the same results, but more efficiently.

GET request to /users/search with the required Accept header for search capabilities:

  • Accept header: application/vnd.staffbase.accessors.users-search.v1+json
  • Use cursor instead of offset for pagination.
  • Add the includeProfile query parameter to retrieve profile data
  • Removed fields (no longer returned in the response):
    • mandatoryGroupIDs
    • groupIDs
    • tags
    • inviteMessage
  • Restructured fields: recoveryCode is now an object
  • Renamed fields:
    • externalID to externalId
    • emails/primary to email

GET request to /usersreturns all user information according to the specified query parameters, but relies on the offset-based pagination, which is not performant for large datasets.

GET request to /users/{userId} with the required Accept header:

  • Accept header: application/vnd.staffbase.accessors.user.v3+json
  • Changes in request parameters:
    • Add the includeProfile query parameter to include profile data
  • Removed fields (no longer returned in the response):
    • mandatoryGroupIDs
    • groupIDs
    • tags
    • inviteMessage
  • Restructured fields: recoveryCode is now an object
  • Renamed fields:
    • externalID to externalId
    • emails/primary to email
  • Identifiers:
    • Both the Staffbase user ID and your external identifier are supported.

GET request to /users/{userId} with all user information.

DELETE request to /users/{userId} with the required Accept header:

  • Accept header: application/vnd.staffbase.accessors.user-delete.v2+json
  • Changes in response:
    • The returned status code has been updated
  • Identifiers:
    • Both the Staffbase user ID and your external identifier are supported.

DELETE request to /users/{userId} to delete user async.

PATCH request to /users/{userId} with required Accept and Content-Type headers:

  • Accept header: application/vnd.staffbase.accessors.user-update.v3+json
  • Content-Type header: application/vnd.staffbase.accessors.user.v1+json
  • Removed fields (no longer returned in the response):
    • mandatoryGroupIDs
    • groupIDs
    • tags
    • inviteMessage
  • Restructured fields: recoveryCode is now an object
  • Renamed fields:
    • externalID to externalId
    • emails/primary to email
  • Changes in HTTP method:
    • Uses PATCH to more clearly indicate partial updates
  • Identifiers:
    • Both the Staffbase user ID and your external identifier are supported

PUT request to /users/{userId} updates fields in the user object but does not replace the object. This behaviour can be confusing, since PUT is generally used for full replacements and does not align with HTTP semantics.

GET request to /users/{userId}/groups/search with required Accept header:

  • Accept header: application/vnd.staffbase.accessors.user.groups-search.v1+json
  • Changes in request parameters:
    • Use cursor instead of offset for pagination
    • Use the query parameter for improved search functionality

GET request to /users/{userId}/groups retrieves all groups for a user, using offset-based pagination, which is less efficient for large datasets.