User API Migration Guide

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.

You have an understanding of the Staffbase versioning policy.

Select a tab

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.

Select a tab

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.

Select a tab

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.

Select a tab

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.

Select a tab

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.

Select a tab

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.

Select a tab

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.

Prerequisite:

Create a new user

Get all users

Search all users

Get a user

Delete a user

Update a user

Retrieve groups for a user