How to Add a Guest to a Folder in ClickUp Using the API

This step-by-step guide explains how to add a guest to a folder in ClickUp with the public API, including required scopes, URL structure, and request body fields so you can integrate this action into your apps or automations.

Understanding the ClickUp guest-to-folder endpoint

The endpoint used to add a guest to a folder in ClickUp is a dedicated API method that connects an existing guest user with a specific folder under a Workspace. It is designed for server-side or backend integrations that already manage authentication and guest creation.

This article is based strictly on the official reference endpoint documented at the ClickUp API Add Guest to Folder page.

Pre-requisites for using the ClickUp API

Before you can successfully call the endpoint to add a guest to a folder, you must meet several requirements related to authentication and data setup.

Required authorization scope in ClickUp

The endpoint requires a specific OAuth scope to allow the action:

• guest:write — This scope is mandatory so the integration can modify guest access.

Make sure your OAuth app or personal token is configured with this scope in ClickUp. Without it, the request will fail with an authorization error.

Guest and folder prerequisites

To add a guest to a folder, the following must already exist:

• A valid Workspace where the folder is located.
• A folder that belongs to that Workspace.
• An existing guest user in the same Workspace.

The endpoint does not create a new guest; it only associates an existing guest user with a folder and sets permissions.

ClickUp endpoint and HTTP method

The API call uses the HTTP POST method and a path that includes both the Workspace identifier and the folder identifier.

ClickUp Add Guest to Folder URL format

The generic URL pattern is:

POST /api/v2/team/{team_id}/folder/{folder_id}/guest/{guest_id}

Each placeholder in the path represents a specific entity inside ClickUp:

• {team_id} — The Workspace (team) ID where the folder and guest exist.
• {folder_id} — The ID of the folder you want to share with the guest.
• {guest_id} — The ID of the guest who will be added to the folder.

Path parameters for the ClickUp request

All three path parameters are required for the endpoint to succeed.

ClickUp team_id (Workspace)

• Parameter: team_id
• Location: Path
• Type: String
• Required: Yes

This value determines which Workspace context the operation runs in. It must match the Workspace where the folder and guest already exist.

ClickUp folder_id

• Parameter: folder_id
• Location: Path
• Type: String
• Required: Yes

This is the identifier of the folder you wish to share with the guest. The folder must belong to the Workspace represented by team_id.

ClickUp guest_id

• Parameter: guest_id
• Location: Path
• Type: String
• Required: Yes

The guest_id must correspond to an existing guest user in the same Workspace. If the ID is invalid or does not point to a guest, the request will not behave as expected.

Request body for the ClickUp API call

The request body is sent as JSON and contains the permission level for the guest plus optional fields that control what the guest can do inside the folder.

Required fields in the ClickUp request body

The primary required property is:

• permission_level — A string that sets the level of access the guest will have on the folder.

The exact supported values are defined in the official API reference document. They represent different levels of access, such as read-only or higher permissions.

Optional fields to refine ClickUp permissions

Depending on the current API specification, additional optional properties may be available in the request body. These might include flags or detailed permission objects that control what the guest is allowed to do inside the folder.

For example, optional fields can be used to:

• Adjust granular sharing or editing rights.
• Set inherited or specific permissions for tasks within the folder.
• Fine-tune collaboration behavior for the guest.

Always refer to the official endpoint documentation to confirm which optional keys are supported and what data types are expected.

Step-by-step: Add a guest to a folder with ClickUp

Follow these steps to integrate the endpoint into your workflow or application.

1. Collect required ClickUp identifiers

1. Retrieve the team_id for the Workspace.
2. Obtain the folder_id for the folder you want to share.
3. Get the guest_id for the existing guest user.

2. Prepare authentication for ClickUp

1. Set up OAuth or API token authentication accepted by the current API.
2. Ensure the token or app has the guest:write scope.
3. Include the authorization header as required by the API documentation.

3. Build the ClickUp request URL

Replace placeholders with real IDs, for example:

POST https://api.clickup.com/api/v2/team/123/folder/456/guest/789

Use your own identifiers where 123, 456, and 789 represent the team, folder, and guest respectively.

4. Define the JSON body for ClickUp

Create a JSON object that contains at least the permission_level field. For example:

{
  "permission_level": "read"
}

Adjust the value based on the allowed permission levels listed in the reference.

5. Send the API request to ClickUp

1. Use your preferred HTTP client (such as curl, Postman, or a programming language library).
2. Set the method to POST.
3. Include the authorization header and content type header.
4. Attach the JSON body.

If the request is valid, the guest will be added to the folder with the specified permissions.

Handling responses from the ClickUp API

The endpoint returns a JSON response that reflects the updated sharing state of the folder and guest. You should parse the response and confirm that:

• The guest is correctly linked to the target folder.
• The permission level matches the value you requested.
• No error fields are present in the response payload.

On error, review the HTTP status code and message to identify issues such as missing scopes, incorrect IDs, or invalid request body fields.

Best practices for working with ClickUp integrations

When building automation or external applications that rely on this endpoint, keep the following integration practices in mind:

• Store and manage Workspace, folder, and guest identifiers securely.
• Limit tokens to only the scopes you need, including guest:write for this operation.
• Implement logging to track when guests are added to folders.
• Handle rate limits and unexpected failures with retries and backoff where appropriate.

For broader consulting or implementation support around automation strategy and API design, you can explore services from firms like Consultevo, which specialize in workflow optimization and tool integration.

Where to find official ClickUp API details

Because API specifications can evolve, always verify the latest behavior, parameters, and examples in the official documentation. You can review the full endpoint specification at the following link:

Add Guest to Folder — ClickUp API Reference

Use that reference together with this how-to article to reliably implement the Add Guest to Folder operation in your integrations.

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

“`