Manage Users in ClickUp Workspaces

/ ClickUp / By

How to Remove a User from a ClickUp Workspace via API

This guide explains how to remove a user from a ClickUp workspace using the official REST API endpoint. You will learn the required permissions, request format, and example payloads so you can safely automate user management in your workspace.

Understanding the ClickUp Remove User Endpoint

The Remove User from Workspace endpoint lets Workspace owners and admins remove a specific member from a chosen team. This operation is performed using a simple HTTP request.

Key details from the official reference:

  • HTTP method: DELETE
  • Authentication: Personal token in the Authorization header
  • Endpoint: Defined by workspace (team) ID and user ID
  • Permissions: Workspace owner or admin role only

You can review the official API specification at the Remove User from Workspace reference page.

Prerequisites for Using the ClickUp API

Before you call the Remove User endpoint, confirm that you have the correct access and identifiers for your ClickUp environment.

1. Required ClickUp Permissions

Only certain roles in a workspace are allowed to remove people. To successfully remove a user, you must be one of the following in that ClickUp workspace:

  • Workspace owner
  • Workspace admin

Members without these roles will receive an error response when trying to remove another user.

2. Get Your ClickUp API Token

You need a valid personal token to authenticate each request to the API. In your ClickUp account settings, generate a token and store it securely. This token will be sent in the HTTP request header.

Header format:

  • Authorization: <your_clickup_api_token>

3. Locate the Team ID and User ID

The Remove User endpoint uses both the workspace (team) ID and the user ID you want to remove. Make sure you know:

  • team_id: The ID of the workspace (also called team in the API).
  • user_id: The ID of the member you want to remove.

You can obtain these IDs from other API endpoints or your integration logic that manages ClickUp data.

ClickUp API Endpoint Format

The Remove User from Workspace endpoint uses a DELETE request to a URL built with both IDs.

General format:

DELETE https://api.clickup.com/api/v2/team/{team_id}/user/{user_id}

Replace the placeholders with actual values from your ClickUp workspace:

  • {team_id} → your workspace (team) ID
  • {user_id} → the user ID you want to remove

Step-by-Step: Remove a User from a ClickUp Workspace

Follow these steps to remove a user using the API. The same process applies across most HTTP clients and programming languages.

Step 1: Build the Request URL

Insert your real team and user IDs into the path. For example:

https://api.clickup.com/api/v2/team/123456/user/987654

This URL targets user 987654 in team 123456 in your ClickUp workspace.

Step 2: Set the HTTP Method

Use the DELETE method, since you are removing a user from the workspace.

Step 3: Add Required Headers

Most tools require at least one header for authentication.

  • Authorization: <your_clickup_api_token>
  • Content-Type: application/json (often included by default, but not strictly required for this DELETE call if there is no body)

Step 4: Do Not Send a Request Body

The Remove User from Workspace endpoint does not require a request body. All necessary information is provided in the URL path and headers. Keep the body empty to match the documented behavior.

Step 5: Send the Request

Use your preferred tool or library, such as:

  • Command line tools like curl
  • API clients such as Postman or Insomnia
  • Server-side code in Node.js, Python, or any language that can send HTTP requests

After sending the request, the API processes the removal operation in your ClickUp workspace.

Example: Remove a User via the ClickUp API

Below is an example of a raw HTTP request to remove a user from a ClickUp workspace. Adjust the IDs and token values to match your real environment.

DELETE /api/v2/team/123456/user/987654 HTTP/1.1
Host: api.clickup.com
Authorization: pk_<your_token_here>

This request tells the ClickUp API to remove the specified user from team 123456, assuming the authenticated token has the correct level of access.

Handling Responses from the ClickUp Endpoint

The Remove User from Workspace endpoint responds with standard HTTP status codes:

  • 200-level: User successfully removed from the ClickUp workspace.
  • 401 Unauthorized: Missing or invalid token in the Authorization header.
  • 403 Forbidden: Authenticated user is not an owner or admin of the workspace.
  • 404 Not Found: The specified team or user ID does not exist in the targeted ClickUp workspace.

The exact response body may vary, but these codes indicate whether the removal worked or if you need to adjust your request.

Best Practices for Automating ClickUp User Management

When integrating this endpoint into a larger automation or admin tool, follow these practices for safer operations in your ClickUp environment:

  • Log every removal: Store the team ID, user ID, and timestamp for auditing.
  • Validate IDs first: Confirm user and team existence using other ClickUp endpoints before calling DELETE.
  • Limit token scope: Use an API token owned by an admin account dedicated to automation, not a personal user account.
  • Handle rate limits: If you remove many users at once, plan for API rate limits and backoff strategies.

When to Use the Remove User Endpoint in ClickUp

This ClickUp API operation is most useful when you are managing many users or integrating with identity or HR systems. Common use cases include:

  • Automatically removing former employees from specific workspaces.
  • Revoking access to project-specific teams after a contract ends.
  • Building an internal admin panel that mirrors ClickUp user membership.

By relying on the official endpoint, you keep your workspace aligned with your organization’s access policies.

Additional Resources for ClickUp API Integrations

For broader guidance on building reliable automations and technical documentation around your ClickUp setup, you can review expert resources at Consultevo. Combine these insights with the official API reference to create stable integrations.

Always confirm the latest details, optional parameters, and example responses in the official ClickUp Remove User from Workspace API documentation. Keeping your implementation synchronized with the official docs ensures your automation continues to work as the platform evolves.

Need Help With ClickUp?

If you want expert help building, automating, or scaling your ClickUp workspace, work with ConsultEvo — trusted ClickUp Solution Partners.

Get Help

“`

Verified by MonsterInsights