How to Use the ClickUp Get Guest API Endpoint

The ClickUp Get Guest API endpoint lets you retrieve detailed information about a single guest in your workspace using their unique guest ID. This guide explains how to call the endpoint, what parameters you need, which OAuth scopes apply, and how to understand the response so you can integrate it safely into your workflows or automation.

What the ClickUp Get Guest Endpoint Does

The Get Guest endpoint in ClickUp is designed to return profile and permission information for one guest. A guest is a limited-access user who can be shared on specific tasks or folders without becoming a full workspace member.

When you call this endpoint, the API returns a JSON object that includes key details, such as:

Guest identification data (like ID and email)
Basic profile information
Membership and sharing details
Permission or access-related fields (where applicable)

Use this endpoint when you need to verify who a guest is, audit guest access, or drive conditional logic in your application based on a guest’s profile or permissions.

Requirements Before Calling the ClickUp Get Guest API

Before using the Get Guest endpoint in ClickUp, ensure you have these essentials in place:

A valid ClickUp workspace where the guest exists
The unique guest_id you want to query
A valid authentication method (Personal Token or OAuth 2.0)
The required OAuth scopes for your integration

Authentication Options in ClickUp

The ClickUp Get Guest endpoint supports authentication through:

Personal Token – suitable for personal scripts or server-side tools.
OAuth 2.0 – recommended for public or user-facing integrations, especially when multiple users will authorize access.

Send the token in the Authorization header as a Bearer token when calling the API.

OAuth Scopes for the ClickUp Get Guest Endpoint

When you use OAuth with ClickUp, your app must request appropriate scopes so it can read guest information. The Get Guest endpoint is read-only and typically requires scopes that allow reading users or guests. Make sure your app requests only the minimum scopes required to pass ClickUp review and to protect user privacy.

ClickUp Get Guest Endpoint URL and Method

The Get Guest endpoint in ClickUp is accessed with a GET request. The URL follows this pattern (see the official reference for exact details):

GET https://api.clickup.com/api/v2/guest/<guest_id>

Replace <guest_id> with the actual ID of the guest you want to retrieve. This ID is typically obtained from other endpoints or administrative tools in ClickUp.

Path Parameter: guest_id

The key path parameter is:

guest_id – a required string or numeric identifier for the guest.

If the guest_id is invalid, does not exist, or does not belong to a workspace accessible to the authorized user, ClickUp will return an error response rather than guest details.

Step-by-Step: How to Call the ClickUp Get Guest API

Follow these steps to correctly call the Get Guest endpoint in ClickUp.

Step 1: Collect the Guest ID

First, obtain the guest_id for the user you want to inspect. You may get this from:

Other user or guest listing endpoints
Admin or security tooling connected to ClickUp
Logs or databases where you store guest references

Confirm that the guest still exists in your ClickUp workspace so the request does not fail.

Step 2: Prepare Your Authorization Token

Next, prepare your authentication token. For most use cases, you will either:

Generate a Personal Token in your ClickUp user settings, or
Use an OAuth 2.0 access token obtained during an authorization flow.

Format the header like this:

Authorization: Bearer YOUR_TOKEN_HERE

Step 3: Build the HTTP Request

Construct a GET request with the endpoint URL and headers. A basic example in raw HTTP form looks like:

GET /api/v2/guest/<guest_id> HTTP/1.1
Host: api.clickup.com
Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/json

Send this request with your preferred HTTP client, such as curl, Postman, or a language SDK that supports ClickUp.

Step 4: Send the Request and Capture the Response

After you send the request, the ClickUp API will return a JSON response. Depending on your client, you should:

Check the HTTP status code.
Parse the JSON body.
Handle any errors gracefully.

Successful responses usually return status code 200, along with the guest object.

Understanding the ClickUp Get Guest Response

The response from this ClickUp endpoint includes a structured JSON object describing the guest. While specific field names are defined in the official reference, you can expect data such as:

ID: the internal guest identifier.
Email: the email address associated with the guest.
Name: the visible name of the guest in ClickUp.
Access details: information about the guest’s workspace or item access.
Metadata: additional configuration or status fields.

Use this information for auditing, permission checks, or to display guest details in your own dashboards or integrations with ClickUp.

Error Handling for the ClickUp Get Guest Endpoint

When calling the Get Guest endpoint, handle common error conditions:

401 Unauthorized: missing, invalid, or expired token.
403 Forbidden: token does not have the required permissions or scopes.
404 Not Found: the guest does not exist or is not visible to the current user.
429 Too Many Requests: rate limits exceeded on the ClickUp API.

Implement retry logic for rate limits and clear user-facing messages for authorization or not-found issues.

Best Practices When Working with ClickUp Guests

To use the Get Guest endpoint responsibly and efficiently, follow these best practices:

Limit exposure: Only request guest information when needed and avoid logging sensitive data.
Cache responses where possible: Reduce repeated calls to the ClickUp API for the same guest.
Validate input: Double-check any guest_id coming from user input or external systems.
Respect permissions: Design your application so it never assumes broader access than what ClickUp grants through scopes.

Use Cases for the ClickUp Get Guest Endpoint

Common scenarios where this endpoint is helpful include:

Automated audits of who has guest access to critical ClickUp spaces.
Custom admin panels that show guest details along with permissions.
Security reviews where you verify the status and identity of each guest.
Integrations that synchronize ClickUp guest records with external systems.

Where to Learn More About the ClickUp API

For the most accurate and up-to-date details about supported fields, request examples, and response schemas, always refer directly to the official ClickUp developer documentation. Here is the specific reference page for the Get Guest endpoint:

ClickUp Get Guest API reference

If you need strategic support implementing large-scale automations or AI-driven workflows on top of ClickUp, you can work with dedicated consultants who specialize in API design, integration patterns, and technical SEO for documentation. A good starting point for expert help is Consultevo, which focuses on advanced implementation and optimization projects.

By following the steps and practices above, you can confidently use the Get Guest endpoint in ClickUp to keep guest data synchronized, secure, and fully aligned with your workspace governance rules.

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

“`