User API Filters

Filter parameters to help you filter the user data retrieved via our User API.

Employee App
Staffbase Intranet

The GET endpoint /api/users/search searches users and supports filtering using the SCIM notation via the filter parameter.

  • Set the followingAccept header to receive the versioned response:
Accept: application/vnd.staffbase.accessors.users-search.v1+json
ParameterDescription
filterSCIM-notation filter expression. See the table below for available properties.
queryFull-text search string across profile fields such as first name, last name, or location. Can be combined with filter.
sortSort order. Allowed values: created_ASC, created_DESC, lastName_ASC_firstName_ASC, updated_DESC, activated_DESC.
cursorCursor used for pagination. Pass the value returned in the previous response to retrieve the next page.
limitNumber of results to return. Allowed values: 1–1000. Defaults to 100).
includeProfileSet to true to include the full profile object (system and custom profile fields) for each user in the response. Defaults to false.
PropertyFilter operatorAllowed values
groupsis member (eq)
not member (ne)		{groupID}
staffbase.creationTypeequal to (eq)
  • csv
  • direct
  • scim
  • sso
staffbase.role
User Role Type		equal to (eq)
  • admin
  • editor
  • moderator
  • reader
staffbase.spaceis member (eq){spaceID}
staffbase.statusequal to (eq)
  • activated (default)
  • deactivated
  • pending
  • contact
created
The point in time when the user was created in the platform.		gt, ge, le, lt, eq, neThe value for the point in time is dynamic. Examples:
  • 2022-05-30
  • 2022-05-30T10:00
  • 2022-05-30T10:00:00.000Z
updated
The point in time when the user was last updated.		gt, ge, le, lt, eq, neThe value for the point in time is dynamic. Examples:
  • 2021-07-07
  • 2021-07-07T10:00
  • 2021-07-07T10:00:00.000Z
deactivated
The point in time when the user was deactivated in the platform.		gt, ge, le, lt, eq, neThe value for the point in time is dynamic. Examples:
  • 2022-05-30
  • 2022-05-30T10:00
  • 2022-05-30T10:00:00.000Z
User typepresent (pr)
  • emails
  • externalId
  • password
  • staffbase.recoveryCode
  • userName
// Only members of the given group ID
groups eq "604fab5e830203614e6fa59d"


// Only members part of the given space ID
staffbase.space eq "5fc7743d3dd910548d350a2a"


// Only registered admin users
staffbase.status eq "activated" and staffbase.role eq "admin"


// Only users created via CSV import or SSO
staffbase.creationType eq "csv" or staffbase.creationType eq "sso"


// Custom profile fields (use the profile field ID for data import)
profile.{fieldID} eq "value"


// -------------------- //
// Different User Types //
// -------------------- //


// Only users with primary email or username and Staffbase password
(emails pr or userName pr) and password pr


// Only access code users (no primary email and username)
(not (emails pr) and not (userName pr) and password pr)


// Only SSO users (identifier, but no Staffbase password)
(externalId pr and not (password pr))


// ---------------------- //
// Filter for Date & Time //
// ---------------------- //


// All users that were created since day = 2021-01-01, time = 10:00
created gt "2021-01-01T10:00"


// All users that were created before day = 2022-01-01
created lt "2022-01-01"


// All users that were updated since day = 2021-07-07, time = 10:00
updated gt "2021-07-07T10:00"


// All users that were updated before day = 2021-05-24
updated lt "2021-05-24"


// All users that were deactivated since day = 2021-07-07, time = 10:00
deactivated gt "2021-07-07T10:00"


// All users that were deactivated before day = 2021-05-24
deactivated lt "2021-05-24"

Since filter is a URL parameter, whitespaces (space = %20) and quotes (” = %22) have to be URL encoded.

Example: Retrieve access-code users with full profile data

Terminal window
export AUTH="Basic TOKEN"


# URL Decoded filter: (not (emails pr) and not (userName pr) and password pr)
curl -X GET 'https://exampleapp.staffbase.com/api/users/search?filter=(not%20(emails%20pr)%20and%20not%20(userName%20pr)%20and%20password%20pr)&includeProfile=true' \
  -H 'Authorization: $AUTH' \
  -H 'Accept: application/vnd.staffbase.accessors.users-search.v1+json' \
  --compressed | json_pp

Example: Retrieve deactivated admin users within a specific time frame

Terminal window
export AUTH="Basic TOKEN"


# URL Decoded filter: staffbase.status eq "deactivated" and staffbase.role eq "admin" and updated gt "2024-01-01"
curl -X GET 'https://exampleapp.staffbase.com/api/users/search?filter=staffbase.status%20eq%20%22deactivated%22%20and%20staffbase.role%20eq%20%22admin%22%20and%20updated%20gt%20%222024-01-01%22' \
  -H 'Authorization: $AUTH' \
  -H 'Accept: application/vnd.staffbase.accessors.users-search.v1+json' \
  --compressed | json_pp