Manage Guests in ClickUp Lists

/ ClickUp / By

How to Remove a Guest from a List in ClickUp via API

This guide explains step by step how to remove a guest from a list in ClickUp using the public REST API. You will learn the required endpoint, headers, parameters, and common troubleshooting tips so you can manage list access programmatically and securely.

Understanding the ClickUp guest removal endpoint

The ClickUp platform exposes a dedicated endpoint to remove a guest from a specific list in your Workspace. This operation must be performed with a valid API token and the correct identifiers for your list and guest.

The operation is carried out with an HTTP DELETE request to the list guest endpoint. When called successfully, this endpoint removes the guest's access to that list. The guest might still retain access to other lists or spaces, depending on your overall sharing configuration.

ClickUp API endpoint for removing a guest

Use the following REST endpoint structure:

  • DELETE https://api.clickup.com/api/v2/list/{list_id}/guest/{guest_id}

Here is what each path parameter represents:

  • list_id: The unique ID of the list from which you want to remove the guest.
  • guest_id: The unique ID of the guest whose access should be removed from that list.

The IDs are usually obtained from previous API responses, such as listing guests or working with list details. Ensure you use the correct values, because invalid IDs will result in an error response.

Prerequisites for using the ClickUp API

Before you call the guest removal endpoint, confirm that you have the following in place in your ClickUp environment:

  • An active ClickUp account with permissions to manage guests and list sharing.
  • A valid ClickUp API token generated from your settings.
  • The target list_id where the guest currently has access.
  • The guest_id of the user you want to remove from the list.

You must keep the API token confidential and store it securely. It authorizes access to operations that affect user permissions in your workspace.

Required headers for the ClickUp request

The guest removal endpoint requires specific HTTP headers. Without them, the request will fail or be rejected.

Mandatory headers for ClickUp API calls

  • Authorization: Your personal API token. Example: Authorization: pk_XXXXXX.
  • Content-Type: application/json. Although this is a DELETE request with no body, including the content type keeps your requests consistent.

Make sure there are no typos in the header names and that your token is active and correctly formatted.

Step-by-step: Remove a guest from a ClickUp list

Follow these steps to remove a guest from a list using the REST API.

1. Gather your ClickUp identifiers

Collect the following values from your environment:

  1. Locate the list_id for the list where the guest currently has access.
  2. Find the guest_id for the guest to be removed.
  3. Confirm your API token has permissions to edit sharing and guest access.

2. Build the ClickUp DELETE request

Construct the full URL using your list and guest IDs:

  • https://api.clickup.com/api/v2/list/<list_id>/guest/<guest_id>

Then configure your HTTP client (such as cURL, Postman, or a backend script) with:

  • Method: DELETE
  • URL: The endpoint above, with IDs replaced by real values.
  • Headers:
    • Authorization: <your_api_token>
    • Content-Type: application/json

3. Send the request to the ClickUp API

Send the DELETE request from your tool of choice:

  • In cURL, you would pass the method, URL, and headers.
  • In Postman, select DELETE, paste the URL, and add headers under the Headers tab.
  • In your application code, use the HTTP client for your language to configure the same method, URL, and headers.

No request body is required for this operation. The path and headers are sufficient for the ClickUp backend to identify the target list and guest.

4. Interpret the ClickUp response

On success, the API responds with a status code in the 2xx range. The documentation for this endpoint indicates that the operation completes without needing a response body. In practice, you should:

  • Check that the HTTP status code indicates success (for example, 200 or 204, depending on implementation).
  • Optionally verify by listing guests for the list in a separate call to confirm the guest is no longer listed.

Troubleshooting ClickUp guest removal issues

If the guest is not removed as expected, review these common causes.

Invalid or missing identifiers

Problems with IDs often trigger error responses. Verify that:

  • The list_id exists in your workspace.
  • The guest_id corresponds to a real guest.
  • The guest actually has access to the target list before removal.

Authorization and permission errors in ClickUp

Authorization problems arise when your token is missing or lacks scope. Check that:

  • Your Authorization header is present and correctly formatted.
  • The token belongs to a user with the ability to manage guests for the list.
  • The workspace settings do not restrict API-based changes beyond your role.

Rate limits and network failure

Most APIs, including the ClickUp API, can enforce rate limits or return network-related errors. If you see these issues:

  • Pause and retry the same request after a short delay.
  • Implement exponential backoff in scripts or integrations.
  • Monitor logs to detect patterns of failed calls.

Best practices for secure ClickUp guest management

Managing guests with the API directly affects who can see data in your workspace. Apply these best practices when using the guest removal endpoint.

Protect your ClickUp API token

  • Never hard-code tokens in client-side code like JavaScript delivered to browsers.
  • Store tokens in environment variables or secure secret managers.
  • Rotate tokens regularly and immediately if you suspect exposure.

Automate ClickUp list access cleanup

You can incorporate the removal endpoint into automation routines:

  • Remove guests automatically when a project closes.
  • Sync guest access with your identity provider or customer lifecycle.
  • Run scheduled scripts that confirm only active guests remain on sensitive lists.

Audit ClickUp guest access regularly

Use the full API to list guests and lists, then compare results to your policies. Regular reviews help you detect:

  • Guests who still have access after projects end.
  • Lists that are shared more broadly than expected.
  • Inconsistencies between manual and automated access management.

Where to learn more about the ClickUp API

For complete technical details, supported status codes, and any recent updates to this endpoint, review the official reference documentation:

If you need broader guidance on building integrations, securing tokens, or designing automation around the ClickUp platform, you can also consult specialized implementation partners:

By following the steps above and relying on the official endpoint, you can confidently manage and remove guest access from any list in your workspace through the ClickUp API.

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

“`