How to Edit Guests in a ClickUp Workspace via API

This guide shows you how to use the ClickUp public API to edit guests in a Workspace, including changing their permissions, personal details, and associated Teams or Spaces.

You will learn the required endpoint, authentication, request body structure, and practical examples so you can automate guest management safely and consistently.

Understanding the ClickUp Edit Guest Endpoint

The Edit Guest on Workspace endpoint lets you update an existing guest’s details at the Workspace level. It is designed for scenarios where you need to maintain access control for external collaborators.

This endpoint is part of the ClickUp API v2 and requires proper authentication using a personal or app token with the correct OAuth scope.

Endpoint Overview

HTTP method: PUT
Base: https://api.clickup.com/api/v2
Path: /team/{team_id}/guest/{guest_id}

In this context, team_id represents the Workspace ID and guest_id is the ID of the guest you want to modify.

Official API reference: Edit Guest on Workspace — ClickUp API.

Authentication and Required Scope in ClickUp

To call this endpoint successfully, you must use an API token or OAuth token in the request header.

Authorization Header

Include the following header with every request:

Authorization: {your_clickup_token}

Replace {your_clickup_token} with your personal token or OAuth access token.

Required OAuth Scope

The endpoint requires the scope:

workspaces:write

Make sure your ClickUp app or integration has this scope approved, otherwise the request will fail with an authorization error.

Path Parameters for ClickUp Workspace Guests

The Edit Guest endpoint relies on two required path parameters.

team_id: The ID of the Workspace where the guest is a member.
guest_id: The ID of the guest account you intend to update.

You can obtain these IDs using other ClickUp API endpoints, such as listing Workspace guests or reading Workspace details.

Request Body for Editing a ClickUp Guest

The request body is a JSON object where you can specify which guest attributes to update. Fields are generally optional; you include only the ones you want to change.

Core Guest Fields

email (string): Update the guest’s email address.
username (string): Change the display name of the guest.
can_edit_tags (boolean): Allow or restrict the ability to edit tags.
can_see_time_estimated (boolean): Control visibility of estimated time.
can_see_time_spent (boolean): Control visibility of time spent.
can_create_views (boolean): Allow or block creating new views.
can_see_time_in_status (boolean): Manage visibility of time in status.
can_see_assigned_comments (boolean): Control whether the guest can see assigned comments.
can_see_custom_fields (boolean): Enable or disable visibility of custom fields.

ClickUp Role and Access Settings

role (string): Guest role within the Workspace. Commonly used to define the level of access at a high level.
invited_by (number): ID of the member who invited the guest. This is usually informational.

Team and Space Permissions in ClickUp

You can fine-tune the guest’s permissions across Teams and Spaces.

teams (array): List of Teams and permissions for each.
spaces (array): List of Spaces and associated sharing rules.

Each object inside these arrays can include IDs and permission flags relevant to that resource. The exact structure may vary, but common fields include the entity ID and booleans that represent allowed actions.

Example: Edit a ClickUp Guest via cURL

The following example demonstrates how to update a guest’s permissions and display name in a Workspace using cURL.

curl -X PUT "https://api.clickup.com/api/v2/team/123/guest/456" \ 
  -H "Authorization: YOUR_CLICKUP_TOKEN" \ 
  -H "Content-Type: application/json" \ 
  -d '{
    "username": "External Designer",
    "can_edit_tags": false,
    "can_see_time_estimated": true,
    "can_see_time_spent": true,
    "can_create_views": false,
    "can_see_custom_fields": true
  }'

Adjust the values based on your Workspace ID, guest ID, and preferred permission configuration.

Step-by-Step: Editing a Guest in ClickUp

Identify the Workspace and guest
Use existing ClickUp endpoints or the app UI to obtain the team_id and guest_id.
Verify your token scope
Confirm that your token has the workspaces:write scope to allow editing Workspace-level data.
Plan the permission model
Decide which fields to change, such as visibility of time tracking, tag editing, and access to custom fields.
Build the JSON payload
Create a JSON object containing the fields you want to update for the guest. Omit anything that should stay unchanged.
Send the PUT request
Make a PUT request to /team/{team_id}/guest/{guest_id} with your authorization header and JSON body.
Validate the response
Check the returned JSON for the updated guest data and confirm the changes appear correctly inside your ClickUp Workspace.

Best Practices for ClickUp Guest Management

Principle of least privilege: Allow only the minimum permissions needed for each guest.
Centralize configuration: Maintain a configuration file or service that defines standard guest profiles.
Automate lifecycle: Combine this endpoint with others to automate onboarding and offboarding of external users.
Audit regularly: Periodically review guest access across Teams and Spaces inside ClickUp to keep your data secure.

Where to Learn More About ClickUp Integrations

For detailed field descriptions, response examples, and up-to-date behavior, review the official ClickUp Edit Guest on Workspace documentation.

If you need help designing scalable workflows or advanced integration patterns around the ClickUp API, you can explore consulting resources at Consultevo.

By following the steps and best practices in this guide, you can confidently control how guests interact with your ClickUp Workspace, maintaining both collaboration and security through the 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

“`