How to Add Guests to Tasks in ClickUp via API

Adding external collaborators to tasks in ClickUp through the API lets you control access without exposing your entire Workspace. This guide walks you step by step through the Add Guest to Task endpoint so you can invite clients, contractors, or stakeholders programmatically and safely.

What the ClickUp Add Guest to Task Endpoint Does

The Add Guest to Task endpoint lets you invite an existing guest to a specific task and configure what they can do with that task. It is designed for controlled sharing, so guests only see what they need, not your full ClickUp Workspace.

With this endpoint you can:

• Link an existing guest to a task by their guest ID.
• Define whether the guest can edit or only view the task.
• Optionally allow the guest to add attachments.
• Use a secure OAuth 2.0 workflow for authorization.

This is especially helpful when your teams manage many client projects in ClickUp and want to automate secure, task-level collaboration.

Prerequisites for Using the ClickUp API

Before you can call the endpoint to add a guest to a task in ClickUp, you need to prepare the following:

1. A ClickUp Workspace and Task

• An active Workspace where API access is enabled.
• The target task already created; you will need its task_id.

2. A Guest Already Created

The endpoint described on the official documentation is for adding an existing guest to a task. Creation of the guest itself is handled by a different endpoint. Make sure you have:

• The guest_id of the person you want to add.
• They are already recognized as a guest in your ClickUp Workspace.

3. OAuth 2.0 Authorization Scopes

Access to this endpoint requires a proper OAuth configuration. For security, ClickUp supports granular scopes, and this operation needs:

• tasks:write — to modify task sharing and permissions.

Ensure your OAuth app has been granted this scope before attempting to call the endpoint.

4. API Base URL

All API requests go through the ClickUp API base URL. The specific endpoint path for this operation is provided in the official reference:

View the Add Guest to Task API documentation

Endpoint Overview: Add Guest to ClickUp Task

The operation is a POST request. In simplified form, the pattern looks like this (consult the official docs for the exact path):

• Method: POST
• Path: includes both task_id and guest_id as parameters in the URL.
• Authentication: OAuth 2.0 Bearer token in the Authorization header.
• Content-Type: application/json for the request body.

Your HTTP client or integration platform should be able to handle these requirements when communicating with ClickUp.

Required Parameters to Add a Guest in ClickUp

Path Parameters

The request URL includes identifiers that tell ClickUp exactly which task and which guest you are targeting:

• task_id — The unique ID of the task you want to share.
• guest_id — The unique ID of the existing guest you are adding to that task.

Headers

Your HTTP request must include:

• Authorization: Bearer <your_oauth_access_token>
• Content-Type: application/json

Request Body Fields

The JSON body controls what the guest can do with the task inside ClickUp. Fields available (as documented) include:

• permissions (object) — Defines the guest’s capabilities on the task. This structure can include flags like:
  • can_edit (boolean) — Whether the guest can edit the task.
  • can_see_subtasks (boolean) — Whether the guest can view subtasks.
  • can_see_time_spent (boolean) — Whether time tracking data is visible.
  • can_see_assignees (boolean) — Whether assignees are visible.
• can_see_comments or similar flags, depending on the current API schema in the documentation.

Refer to the official API reference for the current and complete schema of the permissions object, as ClickUp may add or adjust flags over time.

Step-by-Step: Adding a Guest to a ClickUp Task

Step 1: Collect Required IDs

1. Open the task in ClickUp and retrieve the task_id (often found in the URL or via a list tasks API call).
2. Obtain the guest_id of the person you want to grant access to, from your guests list or via a related endpoint.

Step 2: Configure OAuth Access

1. Register or open your OAuth app in your ClickUp settings.
2. Make sure the app requests the tasks:write scope.
3. Complete the OAuth flow to obtain an access token.

Step 3: Build the HTTP Request

Construct the POST request to the documented endpoint, adding your path parameters and headers. Your request should include:

• The correct URL including task_id and guest_id.
• Authorization: Bearer <access_token> header.
• Content-Type: application/json header.
• A JSON body with your desired permission settings.

Step 4: Send the Request

Use your preferred tool to send the request:

• API client (e.g. Postman, Insomnia).
• Server-side code using a standard HTTP library.
• Automation platforms that support custom webhooks.

On success, ClickUp responds with JSON describing the updated sharing configuration or a related representation of the guest’s access to the task.

Step 5: Verify Guest Access in ClickUp

1. Open the task in the ClickUp interface.
2. Check the sharing or guests section to confirm the guest has been added.
3. Optionally, log in as the guest or use an incognito session to confirm the expected level of access.

Understanding Responses and Errors from ClickUp

When you call the Add Guest to Task endpoint, ClickUp returns a status code and JSON body. While exact structures are detailed in the official docs, common patterns include:

• 2xx Success — The guest has been successfully added to the task.
• 4xx Client Errors — Problems such as missing scopes, invalid IDs, or malformed JSON.
• 5xx Server Errors — Issues on the service side; retry or contact support if persistent.

Typical causes of 4xx errors:

• Using an access token without the tasks:write scope.
• Supplying an incorrect or non-existent task_id or guest_id.
• Omitting required fields in the permissions object.

Best Practices for Managing Guests in ClickUp via API

When integrating this endpoint into your workflow, follow these practices to keep your ClickUp Workspace secure and manageable:

• Grant minimum necessary permissions. Only give guests the capabilities they truly need on a task.
• Automate revocation. When projects end, automatically remove guests from related tasks.
• Validate IDs before requests. Confirm task and guest IDs exist before attempting to add access.
• Log sharing changes. Keep an audit trail of which guests were added to which tasks and when.

Where to Learn More About the ClickUp API

To explore additional options and the most up-to-date schema for this operation, always refer to the official ClickUp documentation:

Official ClickUp Add Guest to Task reference

If you are planning a broader automation or integration strategy around ClickUp, it can be helpful to work with specialists who understand both API design and workflow optimization. You can find consulting support and implementation services at Consultevo.

By following this guide and the official reference, you can confidently add guests to tasks in ClickUp via API, enabling secure external collaboration that scales with your projects.

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

“`