Guests

Add Guest To Task

Changed on Nov 3, 2026

Share a task with a guest.

Note: This endpoint is only available to Workspaces on our Enterprise Plan.

post/v2/task/{task_id}/guest/{guest_id}

Request

Base URL
https://api.clickup.com/api
URL
https://api.clickup.com/api/v2/task/{task_id}/guest/{guest_id}
Auth
API key in header Authorization

Path parameters

task_idstring required

Example:c04

guest_idnumber required

Example:403

Query parameters

include_sharedboolean

Exclude details of items shared with the guest by setting this parameter to false. By default this parameter is set to true.

custom_task_idsboolean

Example:true

If you want to reference a task by it's custom task id, this value must be true.

team_idnumber

Example:123

When the custom_task_ids parameter is set to true, the Workspace ID must be provided using the team_id parameter.
For example: custom_task_ids=true&team_id=123.

Request body

permission_levelstring required

Can be read (view only), comment, edit, or create (full).

Example request

{
  "permission_level": "read"
}

Response

Example response

{
  "guest": {
    "user": {
      "id": 184,
      "username": null,
      "email": "guest@example.com",
      "color": null,
      "profilePicture": null,
      "initials": "G",
      "role": 4,
      "last_active": null,
      "date_joined": null,
      "date_invited": "1583358383412"
    },
    "invited_by": {
      "id": 183,
      "color": "#827718",
      "username": "Jerry",
      "email": "jerry@example.com",
      "initials": "J",
      "profilePicture": "https://attachments.clickup.com/profilePictures/profile.jpg"
    },
    "can_see_time_spent": true,
    "can_see_time_estimated": true,
    "can_edit_tags": true,
    "shared": {
      "tasks": [
        {
          "id": "c04",
          "name": "Task Name",
          "status": {
            "status": "Open",
            "color": "#d3d3d3",
            "type": "open",
            "orderindex": 0
          },
          "orderindex": "0",
          "date_created": "1574718405408",
          "date_updated": "1574722145869",
          "date_closed": null,
          "archived": false,
          "creator": {
            "id": 183,
            "username": "Jerry",
            "color": "#827718",
            "profilePicture": "https://attachments.clickup.com/profilePictures/profile.jpg"
          },
          "assignees": [],
          "checklists": [],
          "tags": [],
          "parent": null,
          "priority": {
            "id": "1",
            "priority": "urgent",
            "color": "#f50000",
            "orderindex": "1"
          },
          "due_date": "1508369194377",
          "start_date": null,
          "points": null,
          "time_estimate": null,
          "custom_fields": [],
          "dependencies": [],
          "team_id": "108",
          "url": "https://app.clickup.com/t/c04",
          "permission_level": "read",
          "list": {
            "id": "1752",
            "name": "Shared with me",
            "access": false
          },
          "folder": {
            "id": "1217",
            "name": "Shared with me",
            "hidden": false,
            "access": false
          },
          "space": {
            "id": "380"
          }
        }
      ],
      "lists": [],
      "folders": []
    }
  }
}

Changes

Nov 3, 2026a0a72ec97ddb Revision changes
- breaking
  the response property //// became nullable for the status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status

Operation history