Offboard Users With the User API

Learn how to offboard users via the User API.

When users leave the organization or do not need access to the Staffbase platform, you can offboard them from the platform.

Although Staffbase offers different methods to offboard users, we recommend using the User API when you need to offboard a large number of users.

In this article, we’ll look at how to offboard users via the User API for different use cases.

Prerequisite

  • You have already generated an API token with administrative access via the Staffbase Studio.

If your application is hosted on the German Hosting Infrastructure, you will need to adjust the base URL used in the request examples. Learn more about it here.

Deactivate User Accounts

  1. If you do not already have the id or externalID of the user, do the following:

    1. Make a GET request to the endpoint /users to list all users. 
    1  export AUTH="Basic TOKEN"
    2

    3  curl -X GET 'https://exampleapp.staffbase.com/api/users' \
    4    -H 'Authorization: $AUTH' \
    5    --compressed | json_pp
    1. Filter the response for the userID of the user.
      Learn more about it here.

  2. Make a PUT request to the endpoint /users/{userID} and in the request body schema, set the status parameter to deactivated.

1  export USERID="5db0221d0a09a219c4ce9218"
2  export AUTH="Basic TOKEN"
3

4  curl "https://exampleapp.staffbase.com/api/users/$userID" \
5    -X PUT \
6    -H "Authorization: $AUTH" \
7    -H "Content-Type: application/json" \
8    --data-raw '{
9    "status": "deactivated"
10  }' \
11    --compressed | json_pp

If you want to activate a deactivated user account, set the status parameter to activated.

Delete All Deactivated User Accounts

  1. Make a GET request to the endpoint /users to list all users with the filter staffbase.status set to deactivated. 
1  export AUTH="Basic TOKEN"
2

3  # URL Decoded: https://exampleapp.staffbase.com/api/users?filter=staffbase.status eq "deactivated"
4  curl -X GET 'https://exampleapp.staffbase.com/api/users?filter=staffbase.status%20eq%20%22deactivated%22' \
5    -H 'Authorization: $AUTH' \
6    --compressed | json_pp

Learn more about user account filters here.

  1. From the list of users in the response, gather the userIDs of deactivated user accounts.
  2. Make a DELETE request to endpoint /users/{userID} for each user.
1  export USERID="5db0221d0a09a219c4ce9218"
2  export AUTH="Basic TOKEN"
3

4  curl "https://exampleapp.staffbase.com/api/users/$userID" \
5    -X DELETE \
6    -H "Authorization: $AUTH" \
7    --compressed | json_pp

Delete All Deactivated User Accounts Within a Specific Time Frame

You can delete user accounts that were deactivated within a specific time period.

  1. Make a GET request to the endpoint /users to list all users with the following parameters:
  • staffbase.status set to deactivated
  • updated set to the desired time frame using the common operators, such as gt, ge, le, lt, eq, n
1  export AUTH="Basic TOKEN"
2

3  # Gathering deactivated users which were updated since 2021-07-07T10:00
4  # URL Decoded: https://exampleapp.staffbase.com/api/users?filter=staffbase.status eq "deactivated" and updated gt "2021-07-07T10:00"
5  curl -X GET 'https://exampleapp.staffbase.com/api/users?filter=staffbase.status%20eq%20%22deactivated%22%20and%20updated%20gt%20%222021-07-07T10%3A00%22' \
6    -H 'Authorization: $AUTH' \
7    --compressed | json_pp

Learn more about user account filters here.

  1. From the list of users in the response, gather the userIDs of deactivated user accounts.
  2. Make a DELETE request to endpoint /users/{userID}.
1  export USERID="5db0221d0a09a219c4ce9218"
2  export AUTH="Basic TOKEN"
3

4  curl "https://exampleapp.staffbase.com/api/users/$userID" \
5    -X DELETE \
6    -H "Authorization: $AUTH" \
7    --compressed | json_pp

Delete Pending User Accounts

Pending user accounts belong to those users who have been invited to the Staffbase platform but yet to register in the platform. You can clean up the pending user accounts by deleting them from the platform.

  1. Make a GET request to the endpoint /users to list all users with the filter staffbase.status set to pending. 
1  export AUTH="Basic TOKEN"
2

3  # URL Decoded: https://exampleapp.staffbase.com/api/users?filter=staffbase.status eq "pending"
4  curl -X GET 'https://exampleapp.staffbase.com/api/users?filter=staffbase.status%20eq%20%22pending%22' \
5    -H 'Authorization: $AUTH' \
6    --compressed | json_pp

Learn more about user account filters here.

  1. From the list of users in the response, gather the userIDs of pending user accounts.
  2. Make a DELETE request to the endpoint /users/{userID} for each user.
1  export USERID="5db0221d0a09a219c4ce9218"
2  export AUTH="Basic TOKEN"
3

4  curl "https://exampleapp.staffbase.com/api/users/$userID" \
5    -X DELETE \
6    -H "Authorization: $AUTH" \
7    --compressed | json_pp

Deleting All User Accounts with a Certain Tag

Your users can have tags on their profiles. These tags are custom-defined attributes. They can be created based on departments, interest groups, or locations. Learn more here.

  1. Make a GET request to the endpoint /users to list all users and filter for:

  • user accounts with staffbase.status set to one of following:

    • pending
    • activated
    • deactivated
    1  export AUTH="Basic TOKEN"
    2

    3  # URL Decoded: https://exampleapp.staffbase.com/api/users?filter=staffbase.status eq "deactivated" or staffbase.status eq "activated" or staffbase.status eq "pending"
    4  curl -X GET 'https://exampleapp.staffbase.com/api/users?filter=staffbase.status%20eq%20%22deactivated%22%20or%20staffbase.status%20eq%20%22activated%22%20or%20staffbase.status%20eq%20%22pending%22' \
    5    -H 'Authorization: $AUTH' \
    6    --compressed | json_pp

To get all the tags used in the platform, make a GET request to the endpoint /tags.

  1. Filter the list of users in the response for the desired tag and gather the userIDs of those accounts.

  2. Make a DELETE request to the endpoint /users/{userID} for each user.

1  export USERID="5db0221d0a09a219c4ce9218"
2  export AUTH="Basic TOKEN"
3

4  curl "https://exampleapp.staffbase.com/api/users/$userID" \
5    -X DELETE \
6    -H "Authorization: $AUTH" \
7    --compressed | json_pp