openapi: 3.2.0 info: title: ClickUp API v2 Reference User Groups API description: The ClickUp API enables you to programmatically access and manage your ClickUp resources. contact: {} version: '2.0' servers: - url: https://api.clickup.com/api description: ClickUp variables: {} security: - Authorization_Token: [] tags: - name: User Groups paths: /v2/team/{team_id}/group: parameters: [] post: summary: Create Group tags: - User Groups description: 'This endpoint creates a User Group within a Workspace.\ \ User Groups are used to organize and manage users within a Workspace.\ \ In the API documentation, `team_id` refers to the Workspace ID, and `group_id` refers to the User Group ID.\ \ **Note:** Adding a guest with view-only permissions to a Team automatically converts them to a paid guest.\ \ If no paid guest seats are available, an additional member seat will be added, increasing the number of paid guest seats.\ \ This change incurs a prorated charge based on the billing cycle.' operationId: CreateUserGroup parameters: - name: team_id in: path description: Workspace ID required: true style: simple schema: type: number contentEncoding: double examples: - 123 requestBody: description: '' content: application/json: schema: title: CreateTeamrequest required: - name - members type: object properties: name: type: string handle: type: string members: type: array items: type: integer contentEncoding: int32 description: '' examples: - name: New team name handle: newteamname members: - 123456 - 987654 example: name: New User Group name handle: newusergroupname members: - 123456 - 987654 required: true responses: '200': description: '' headers: {} content: application/json: schema: title: CreateTeamresponse required: - id - team_id - userid - name - handle - date_created - initials - members - avatar type: object properties: id: type: string team_id: type: string userid: type: integer contentEncoding: int32 name: type: string handle: type: string date_created: type: string initials: type: string members: type: array items: title: Members1 required: - id - username - email - color - initials - profilePicture type: object properties: id: type: integer contentEncoding: int32 username: type: string email: type: string color: type: string initials: type: string profilePicture: type: string examples: - id: 185 username: Sam email: sam@example.com color: '#4169E1' initials: S profilePicture: https://attachments.clickup.com/profilePictures/profile.jpg description: '' avatar: $ref: '#/paths/~1v2~1group~1{group_id}/put/responses/200/content/application~1json/schema/properties/avatar' examples: - id: 4bfdfcec-6f4f-40a7-b0d6-22660d51870d team_id: '301540' userid: 301828 name: User group handle: usergroup date_created: '1640122639829' initials: U members: - id: 185 username: Sam email: sam@example.com color: '#4169E1' initials: S profilePicture: https://attachments.clickup.com/profilePictures/profile.jpg - id: 186 username: Alex email: alex@example.com color: '#4169E1' initials: A profilePicture: https://attachments.clickup.com/profilePictures/profile.jpg avatar: attachment_id: null color: null source: null icon: null example: id: 4bfdfcec-6f4f-40a7-b0d6-22660d51870d team_id: '301540' userid: 301828 name: User group handle: usergroup date_created: '1640122639829' initials: U members: - id: 185 username: Sam email: sam@example.com color: '#4169E1' initials: S profilePicture: https://attachments.clickup.com/profilePictures/profile.jpg - id: 186 username: Alex email: alex@example.com color: '#4169E1' initials: A profilePicture: https://attachments.clickup.com/profilePictures/profile.jpg avatar: attachment_id: null color: null source: null icon: null deprecated: false /v2/group/{group_id}: parameters: [] put: summary: Update Group tags: - User Groups description: 'This endpoint is used to manage User Groups, which are groups of users within your Workspace.\ \ In our API, `team_id` in the path refers to the Workspace ID, and `group_id` refers to the ID of a User Group.\ \ **Note:** Adding a guest with view-only permissions to a User Group automatically converts them to a paid guest.\ \ If you don''t have any paid guest seats available, a new member seat is automatically added to increase the number of paid guest seats.\ \ This incurs a prorated charge based on your billing cycle.' operationId: UpdateTeam parameters: - name: group_id in: path description: User Group ID required: true style: simple schema: type: string examples: - C9C58BE9 requestBody: description: "The group handle can be updated, which is used to @mention a User Group within the Workspace.\\\n \\\nModify Group members by using the \"add\" and \"rem\" parameters with an array of user IDs to include or exclude members." content: application/json: schema: title: UpdateTeamrequest type: object properties: name: type: string handle: type: string members: title: Members2 required: - add - rem type: object properties: add: type: array items: type: integer contentEncoding: int32 description: '' rem: type: array items: type: integer contentEncoding: int32 description: '' examples: - add: - 123456 - 987654 rem: - 159753 examples: - name: New User Group Name handle: newusergroupname members: add: - 123456 - 987654 rem: - 159753 example: name: New User Group Name handle: newusergroupname members: add: - 123456 - 987654 rem: - 159753 required: true responses: '200': description: '' headers: {} content: application/json: schema: title: UpdateTeamresponse required: - id - team_id - userid - name - handle - date_created - initials - members - avatar type: object properties: id: type: string team_id: type: string userid: type: integer contentEncoding: int32 name: type: string handle: type: string date_created: type: string initials: type: string members: type: array items: title: Members3 required: - id - username - email - color - initials - profilePicture type: object properties: id: type: integer contentEncoding: int32 username: type: string email: type: string color: type: string initials: type: string profilePicture: type: - string - 'null' examples: - id: 201 username: Jim Halpert email: jim@example.com color: '#40BC86' initials: JH profilePicture: null description: '' avatar: title: Avatar required: - attachment_id - color - source - icon type: object properties: attachment_id: type: - string - 'null' color: type: - string - 'null' source: type: - string - 'null' icon: type: - string - 'null' examples: - attachment_id: null color: null source: null icon: null examples: - id: 4bfdfcec-6f4f-40a7-b0d6-22660d51870d team_id: '123456' userid: 301828 name: New User Group Name handle: newusergroupname date_created: '1640122639829' initials: NN members: - id: 201 username: Jim Halpert email: jim@example.com color: '#40BC86' initials: JH profilePicture: null - id: 202 username: Dwight Shrute email: dwight@example.com color: '#FF8600' initials: DS profilePicture: null avatar: attachment_id: null color: null source: null icon: null example: id: 4bfdfcec-6f4f-40a7-b0d6-22660d51870d team_id: '123456' userid: 301828 name: New User Group Name handle: newusergroupname date_created: '1640122639829' initials: NN members: - id: 201 username: Jim Halpert email: jim@example.com color: '#40BC86' initials: JH profilePicture: null - id: 202 username: Dwight Shrute email: dwight@example.com color: '#FF8600' initials: DS profilePicture: null avatar: attachment_id: null color: null source: null icon: null deprecated: false delete: summary: Delete Group tags: - User Groups description: 'This endpoint is used to remove a User Group from your Workspace.\ \ In our API documentation, `team_id` refers to the id of a Workspace, and `group_id` refers to the id of a user group.' operationId: DeleteTeam parameters: - name: group_id in: path description: User Group ID required: true style: simple schema: type: string examples: - C9C58BE9 responses: '200': description: '' headers: {} content: application/json: schema: type: object examples: - {} contentMediaType: application/json example: {} deprecated: false /v2/group: parameters: [] get: summary: Get Groups tags: - User Groups description: 'This endpoint is used to view User Groups in your Workspace.\ \ In our API documentation, `team_id` refers to the ID of a Workspace, and `group_id` refers to the ID of a User Group.' operationId: GetTeams1 parameters: - name: team_id in: query description: 'Workspace ID. **Note**: For this endpoint, `team_id`` is a required query parameter.' required: true style: form explode: true schema: type: number contentEncoding: double examples: - 123 - name: group_ids in: query description: "Enter one or more User Group IDs to retrieve information about specific User Group(s).\\\n \\\nFor example: \\\n \\\n`?team_id=12456&group_ids=ABC12345&group_ids=DEF98765`" style: form explode: true schema: type: array items: type: string examples: - C9C58BE9-7C73-4002-A6A9-123456789123 - F3B51AE4-6F25-1783-D2C1-987654321321 responses: '200': description: '' headers: {} content: application/json: schema: title: GetTeamsresponse required: - groups type: object properties: groups: type: array items: title: Group required: - id - team_id - userid - name - handle - date_created - initials - members - avatar type: object properties: id: type: string team_id: type: string userid: type: integer contentEncoding: int32 name: type: string handle: type: string date_created: type: string initials: type: string members: type: array items: $ref: '#/paths/~1v2~1group~1{group_id}/put/responses/200/content/application~1json/schema/properties/members/items' description: '' avatar: $ref: '#/paths/~1v2~1group~1{group_id}/put/responses/200/content/application~1json/schema/properties/avatar' examples: - id: 4bfdfcec-6f4f-40a7-b0d6-22660d51870d team_id: '123456' userid: 301123 name: product team handle: product date_created: '1640122639829' initials: PT members: - id: 183 username: Jerry email: jerry@example.com color: '#40BC86' initials: J profilePicture: null - id: 184 username: Sam email: sam@example.com color: '#FF8600' initials: S profilePicture: null avatar: attachment_id: null color: null source: null icon: null description: '' examples: - groups: - id: 4bfdfcec-6f4f-40a7-b0d6-22660d51870d team_id: '123456' userid: 301123 name: product team handle: product date_created: '1640122639829' initials: PT members: - id: 183 username: Jerry email: jerry@example.com color: '#40BC86' initials: J profilePicture: null - id: 184 username: Sam email: sam@example.com color: '#FF8600' initials: S profilePicture: null avatar: attachment_id: null color: null source: null icon: null - id: fd31be63-41f2-4320-9043-9786fdf643d6 team_id: '301540' userid: 301828 name: HR department handle: hr-dept date_created: '1627087990293' initials: HD members: - id: 183 username: Jerry email: jerry@example.com color: '#40BC86' initials: J profilePicture: https://attachments.clickup.com/profilePictures/profile.jpg avatar: attachment_id: null color: null source: null icon: null example: groups: - id: 4bfdfcec-6f4f-40a7-b0d6-22660d51870d team_id: '123456' userid: 301123 name: product managers handle: product date_created: '1640122639829' initials: PT members: - id: 183 username: Jerry email: jerry@example.com color: '#40BC86' initials: J profilePicture: null - id: 184 username: Sam email: sam@example.com color: '#FF8600' initials: S profilePicture: null avatar: attachment_id: null color: null source: null icon: null - id: fd31be63-41f2-4320-9043-9786fdf643d6 team_id: '301540' userid: 301828 name: HR department handle: hr-dept date_created: '1627087990293' initials: HD members: - id: 183 username: Jerry email: jerry@example.com color: '#40BC86' initials: J profilePicture: https://attachments.clickup.com/profilePictures/profile.jpg avatar: attachment_id: null color: null source: null icon: null deprecated: false components: securitySchemes: Authorization_Token: name: Authorization type: apiKey in: header description: 'API token required for authentication. Two types of tokens are supported: **Personal API Key** Obtain from ClickUp''s settings page under ''Apps'' and add it to the header as `Authorization: pk_...` **OAuth2 Access Token** Generated through the OAuth2 flow and add it to the header as `Authorization: Bearer {access_token}`'