×

ClickUp guest workspace invites

/ ClickUp / By

How to Invite a Guest to a ClickUp Workspace via API

This guide explains how to invite a guest to a ClickUp workspace using the public REST API, including required permissions, request structure, and common responses.

Overview of the ClickUp guest invite endpoint

The ClickUp API provides a dedicated endpoint to invite external users, known as guests, into a specific workspace. Guests can collaborate without having full-member access, making this endpoint ideal for clients, contractors, or partners.

The operation is handled by the POST /v2/workspace/{workspace_id}/guest endpoint and requires a valid token with the correct scopes.

  • Method: POST
  • Base path: /v2/workspace/{workspace_id}/guest
  • Authentication: Personal or OAuth token
  • Response: JSON representing the created or updated guest

Prerequisites for using the ClickUp API

Before calling the guest invite endpoint, you must have the following in place:

  • A valid ClickUp workspace ID
  • An API token or OAuth token with the correct permissions
  • Access to make HTTPS requests (for example, via cURL, Postman, or custom code)

Required ClickUp permissions and scopes

The endpoint is protected by specific scopes. You must ensure your token includes:

  • workspaces:write – required to invite or modify guests in the workspace
  • For OAuth apps, make sure the workspace where you will invite the guest is included in the user authorization

If your token does not include the proper scope, the API will return an HTTP 401 or 403 error, depending on whether the token is missing or lacks authority.

Understanding the ClickUp guest invite request

The guest invite request body defines who you are inviting and how they can interact with the workspace. You send this data as JSON in the POST request body.

Path parameter: workspace_id

The workspace_id path parameter identifies the workspace where the guest will be invited. This value is required and must correspond to a workspace accessible with your token.

  • Type: string
  • Required: yes
  • Example: 123456

ClickUp guest request body fields

The request body accepts several properties. The exact fields can differ by version, but they typically include:

  • email – The email address of the guest being invited.
  • can_edit or similar permissions flags – Determines whether the guest can edit items or is restricted to view-only access.
  • invite_source or related metadata – Optional data to track the origin of the invitation.
  • teams or spaces assignment fields – Optional, used to limit the guest to specific parts of the workspace if supported.

All fields must conform to the types and validation rules defined in the official API schema. For more precise property names and requirements, always review the official reference.

Step-by-step: Invite a guest to a ClickUp workspace

Follow these steps to invite a guest using the ClickUp API endpoint.

Step 1: Prepare your authentication token

  1. Generate a personal token in your ClickUp account or complete the OAuth flow for your integration.
  2. Verify that the token has the workspaces:write scope.
  3. Store the token securely. You will send it in the Authorization header as a Bearer token.

Step 2: Identify the ClickUp workspace

  1. Locate the workspace ID from your ClickUp settings or using a related workspace retrieval endpoint.
  2. Confirm that the workspace is associated with the token you will use.
  3. Substitute this value into the path parameter {workspace_id} in the URL.

Step 3: Build the HTTPS request

Construct an HTTPS POST request to the guest invite endpoint. The following structure outlines the required components:

  • URL: https://api.clickup.com/api/v2/workspace/{workspace_id}/guest
  • Method: POST
  • Headers:
    • Authorization: Bearer <your_token>
    • Content-Type: application/json
  • Body: JSON containing the guest details and permissions.

A typical JSON body might resemble the following pattern (adapt the field names based on the reference):

{
  "email": "guest@example.com",
  "can_edit": true,
  "note": "Client access for project review"
}

Make sure your field names, data types, and optional properties all follow the official specification.

Step 4: Send the request and verify the response

  1. Send the POST request from your HTTP client of choice.
  2. On success, you should receive a 200 or 201 HTTP status code and a JSON response describing the guest.
  3. Store any returned IDs if you plan to update or revoke the guest later.

Handling ClickUp API responses and errors

When you invite a guest to a ClickUp workspace, the API will respond with a JSON object or an error. Use the HTTP status code and message to guide troubleshooting.

Successful responses

Common success characteristics include:

  • Status code: 200 or 201
  • Body: JSON with details of the guest, including their ID and any workspace-specific configuration
  • Use case: Confirm that the guest email, permissions, and associated workspace are correct.

Error responses and troubleshooting

The endpoint may return various error codes. The most common include:

  • 400 Bad Request – The JSON body is invalid, a required field is missing, or the email format is incorrect.
  • 401 Unauthorized – The ClickUp token is missing, expired, or invalid.
  • 403 Forbidden – The token lacks the workspaces:write scope or does not have access to the target workspace.
  • 404 Not Found – The workspace ID is incorrect or does not exist for the current user or app.
  • 409 Conflict – The guest may already exist or there is a conflicting state with the invitation.

When you receive an error, log both the HTTP status code and the returned error body. Use these details to adjust your request or update your ClickUp permissions.

Best practices for automating ClickUp guest invites

To make your integration reliable and secure, follow these best practices when automating guest invitations in a ClickUp workspace.

  • Validate input – Check email addresses and required fields before making API calls.
  • Use least privilege – Grant only the necessary permissions to tokens used to invite guests.
  • Handle idempotency – If a guest may be invited multiple times, detect existing guests before creating new ones, if the API model supports that pattern.
  • Monitor quotas – Respect any ClickUp rate limits by introducing retries with backoff and logging.

Testing your ClickUp integration

Always test your guest invitation flow in a controlled environment:

  • Use a dedicated test workspace in ClickUp.
  • Invite non-production email accounts to avoid exposing client data.
  • Verify permissions by logging in as the guest and confirming the expected access.

Where to learn more about the ClickUp API

For the exact schema, field list, and up-to-date behavior of the guest invitation endpoint, consult the official ClickUp developer documentation. The reference page includes request and response samples, rate limit notes, and error descriptions.

You can view the endpoint details here: ClickUp Invite Guest to Workspace API.

If you are building a larger integration, you may also want strategic guidance on API design, automation architecture, or SEO-driven documentation. For expert assistance, visit Consultevo for consulting services.

By following the steps and considerations in this tutorial, you can securely invite guests into a ClickUp workspace using the public API, control their permissions, and integrate external collaborators into your workflows in a consistent, automated way.

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

“`

Verified by MonsterInsights