Add Guests to ClickUp Lists

/ ClickUp / By

How to Add Guests to ClickUp Lists via API

Using the ClickUp API, you can programmatically add guests to specific task lists and control how they collaborate in your workspace. This guide walks you through the required endpoint, headers, body parameters, permissions, and common implementation patterns for safely inviting guests to lists.

Understanding the ClickUp guest list endpoint

To add a guest to a list, the ClickUp public API exposes a dedicated endpoint that attaches an existing guest to a chosen list in your workspace. This operation is list-scoped, which means it only affects the permissions and access on that single list.

The operation is a POST request to the guest management endpoint for lists. You must supply:

  • The unique identifier of the list.
  • The unique identifier of the guest user.
  • A flag that defines whether the guest can edit or only view the list.

This action is subject to permission checks. Only authorized users or tokens with sufficient scopes in ClickUp can successfully add guests to lists.

Prerequisites for using the ClickUp API

Before you can add guests to a list using the ClickUp API, ensure you have the following items ready in your integration environment:

  • An active ClickUp workspace.
  • A valid API token generated in the workspace.
  • The list ID where you want to add the guest.
  • The guest ID of the user you want to attach to the list.

The API token must have the appropriate access rights to manage list sharing and guest permissions. Treat your token as a secret and avoid embedding it directly in public front-end code.

ClickUp endpoint overview for adding a guest

The main pieces of information you need are the HTTP method, the URL path pattern, and the headers you must send. The official reference for this operation is available on the ClickUp developer site: Add guest to list endpoint.

Key points about the endpoint:

  • Method: POST
  • Scope: List-level guest sharing
  • Purpose: Attach an existing guest to a list and define whether they can edit

Required headers for the ClickUp request

Your API call must include specific headers so that the ClickUp platform can authenticate and parse your request correctly:

  • Authorization: Your API token, usually passed as a simple token string (for example, Authorization: <your-token>). This header is mandatory.
  • Content-Type: application/json to indicate you are sending a JSON body.

Make sure the Authorization header is present in every call. Omitting or misconfiguring this header will cause authentication errors, and the guest will not be added to the list.

ClickUp request body parameters

The request body is a JSON object that defines the guest to add and their access level. The ClickUp API expects specific fields:

  • guest_id (required, string or integer depending on your implementation): the unique identifier of the guest you are adding to the list.
  • can_edit (required, boolean): indicates whether the guest can edit tasks and content in the list. Use true to grant edit permissions or false for view-only access.

The body must be valid JSON. An invalid or missing field will cause a validation error from the API. Always double-check your data types and property names before sending the request.

Step-by-step: Add a guest to a ClickUp list

Follow the steps below to structure your integration workflow. These steps are language-agnostic and apply whether you use cURL, Node.js, Python, or another HTTP client.

Step 1: Collect required ClickUp identifiers

Gather the following values from your workspace and existing systems:

  1. API token: Generated from your ClickUp account or workspace settings.
  2. List ID: The list you want to share with the guest. This is often available from other API calls or your workspace URL pattern.
  3. Guest ID: The unique identifier of the guest. The guest must already exist in your workspace as a guest user.

Store these values securely and avoid hard-coding them into source code repositories when possible.

Step 2: Build the ClickUp POST request

Next, construct the POST request using your preferred HTTP client. The structure generally includes:

  • The full endpoint URL including the list identifier.
  • The Authorization and Content-Type headers.
  • A JSON body with the guest_id and can_edit fields.

Example logical structure:

  • URL: a list-sharing endpoint for guests.
  • Headers:
    • Authorization: <your-clickup-api-token>
    • Content-Type: application/json
  • Body:
    • { "guest_id": <guest-id>, "can_edit": true }

Replace the placeholder values with actual IDs and desired permission flags from your environment.

Step 3: Send the request and handle responses

When you send the POST request to the ClickUp API, you should be prepared to handle both successful and error responses. Typical behavior includes:

  • Success: The API returns a response object confirming that the guest has been added to the list, often including sharing details, guest information, or list identifiers.
  • Client errors: If required data is missing or malformed, the API may respond with 4xx status codes. Check the error message to identify invalid fields or missing permissions.
  • Authorization errors: If your token is incorrect, expired, or does not have sufficient permissions, you may receive an unauthorized or forbidden status.

Implement logging and error handling so you can quickly diagnose issues when integrating with production systems.

Managing permissions for guests in ClickUp

Proper permission management is crucial when sharing lists with guests. The main control you have during this operation is the can_edit flag. Setting this flag defines how broadly guests can participate in your workflows.

Choosing the correct ClickUp guest access level

Use the can_edit value according to your collaboration and security requirements:

  • View-only access (false): Choose this option when guests should only review tasks, statuses, and comments without making changes.
  • Edit access (true): Use this when guests need to actively contribute to tasks, update fields, or change statuses on the list.

Review your organization policies before enabling broad editing rights to external collaborators.

Security best practices for ClickUp integrations

When integrating with the ClickUp API, especially for actions that modify access control, follow standard security practices:

  • Store API tokens in environment variables or a secure secret manager.
  • Use server-side code or trusted back-end services to perform API calls.
  • Implement role-based access control on your side before calling the API to add any guest.
  • Log only non-sensitive metadata; avoid writing raw tokens into logs.

These practices help prevent unauthorized access and ensure your workspace remains secure as you automate guest management.

Troubleshooting common ClickUp API issues

When working with the guest-to-list endpoint, you may encounter some common problems:

  • Invalid guest ID: If the guest identifier does not match an existing guest in your workspace, the request will fail. Verify that the user has been added as a guest beforehand.
  • Missing permissions: If your token does not have rights to manage guests on the target list, you may receive a forbidden error. Check token scopes and workspace settings.
  • Malformed JSON: Any syntax error in the request body, such as missing commas or incorrect property names, will cause the server to reject the request.
  • Rate limits: Large-scale automations may hit rate limits. In that case, implement retries with backoff and monitor the rate-limit headers returned by the API.

Refer back to the official documentation if a response code is unclear or if additional parameters are introduced in newer versions of the API.

Next steps and additional resources for ClickUp developers

Once you can reliably add guests to lists using the API, you can extend your integration to cover more workspace automation scenarios, such as automatically inviting guests to project-specific lists or syncing external user directories with list-sharing rules.

For broader process and integration strategies, you can explore technical consulting resources like Consultevo, which focus on workflow design and systems integration. For endpoint-specific details and any future changes to parameters or behaviors, always cross-check the latest documentation on the ClickUp developer portal at this reference page.

By combining secure token management, clear permission strategies, and robust error handling, your application can use the ClickUp API to manage guest access at scale while keeping your workspace organized and controlled.

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

“`