Laurel User Groups API
The User Groups API from Laurel — 6 operation(s) for user groups.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/laurel-user-groups-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Identity Service Ably User Groups API
description: ''
version: '1'
contact: {}
servers: []
security:
- ApiBearerAuth: []
tags:
- name: User Groups
paths:
/api/v1/user-groups:
get:
operationId: UserGroupController_list_v1
parameters:
- name: customerId
required: true
in: query
description: The customer ID who this group belongs to
schema:
format: objectid
type: string
- name: ids
required: false
in: query
description: Optional IDs to filter groups (can be user IDs or timekeeper IDs depending on kind parameter)
schema:
type:
- array
- 'null'
items:
type: string
- name: kind
required: true
in: query
description: The kind of IDs to use for filtering and response format (user-id or timekeeper-id)
schema:
enum:
- timekeeper-id
- user-id
type: string
responses:
'200':
description: List of user groups
content:
application/json:
schema:
items:
oneOf:
- $ref: '#/components/schemas/UserGroupDto'
type: array
summary: List user groups for a customer
tags:
- User Groups
post:
operationId: UserGroupController_create_v1
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserGroupDto'
responses:
'201':
description: The created user group
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserGroupDto'
summary: Create a user group
tags:
- User Groups
/api/v1/user-groups/by-external-id/{externalId}:
put:
description: Creates the group if no live group exists for the given (customerId, externalId), otherwise partially updates the existing one. Fields present in the payload overwrite; omitted fields are left unchanged. The externalId is the stable key and is never mutated. Idempotent.
operationId: UserGroupController_upsertByExternalId_v1
parameters:
- name: externalId
required: true
in: path
schema:
type: string
- name: customerId
required: true
in: query
description: The customer ID who this group belongs to
schema:
format: objectid
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertUserGroupByExternalIdDto'
responses:
'200':
description: The created or updated user group
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserGroupDto'
summary: Upsert a user group by its external id
tags:
- User Groups
delete:
operationId: UserGroupController_deleteByExternalId_v1
parameters:
- name: externalId
required: true
in: path
schema:
type: string
- name: customerId
required: true
in: query
description: The customer ID who this group belongs to
schema:
format: objectid
type: string
responses:
'204':
description: User group deleted successfully
summary: Delete a user group by its external id
tags:
- User Groups
/api/v1/user-groups/for-user/{userId}:
get:
description: Returns the user groups the given user is a member of. A user acting as themselves may call this with only `CustomerOwnUserOwnRead`; otherwise requires `CustomerOwnUserAnyRead` or `CustomerAnyUserAnyRead`.
operationId: UserGroupController_listForUser_v1
parameters:
- name: userId
required: true
in: path
schema:
format: objectid
type: string
- name: customerId
required: true
in: query
description: The customer ID the user belongs to
schema:
format: objectid
type: string
responses:
'200':
description: List of user groups the user is a member of
content:
application/json:
schema:
items:
oneOf:
- $ref: '#/components/schemas/UserGroupDto'
type: array
summary: List user groups a specific user is a member of
tags:
- User Groups
/api/v1/user-groups/{userGroupId}:
get:
operationId: UserGroupController_get_v1
parameters:
- name: userGroupId
required: true
in: path
description: user group's id
schema:
format: objectid
type: string
- name: customerId
required: true
in: query
description: customer's id
schema:
format: objectid
type: string
responses:
'200':
description: The user group
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserGroupDto'
summary: Get a single user group
tags:
- User Groups
patch:
operationId: UserGroupController_update_v1
parameters:
- name: userGroupId
required: true
in: path
description: user group's id
schema:
format: objectid
type: string
- name: customerId
required: true
in: query
description: customer's id
schema:
format: objectid
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserGroupDto'
responses:
'200':
description: The updated user group
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserGroupDto'
summary: Update a user group
tags:
- User Groups
delete:
operationId: UserGroupController_delete_v1
parameters:
- name: userGroupId
required: true
in: path
description: user group's id
schema:
format: objectid
type: string
- name: customerId
required: true
in: query
description: customer's id
schema:
format: objectid
type: string
responses:
'200':
description: The deleted user group, or null if not found
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserGroupDto'
summary: Delete a user group
tags:
- User Groups
/api/v1/user-groups/{userGroupId}/users:
get:
operationId: UserGroupController_getUsersInGroup_v1
parameters:
- name: userGroupId
required: true
in: path
description: user group's id
schema:
format: objectid
type: string
- name: customerId
required: true
in: query
description: customer's id
schema:
format: objectid
type: string
responses:
'200':
description: List of users in the group
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserGroupUserResponseDto'
summary: Get all users in a user group
tags:
- User Groups
post:
operationId: UserGroupController_addUsers_v1
parameters:
- name: userGroupId
required: true
in: path
description: user group's id
schema:
format: objectid
type: string
- name: customerId
required: true
in: query
description: customer's id
schema:
format: objectid
type: string
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AddUserIdsToGroupDto'
- $ref: '#/components/schemas/AddTimekeeperIdsToGroupDto'
responses:
'201':
description: The updated user group
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserIdUserGroupDto'
- $ref: '#/components/schemas/TimekeeperIdUserGroupDto'
summary: Add users to a user group
tags:
- User Groups
delete:
operationId: UserGroupController_removeUsers_v1
parameters:
- name: userGroupId
required: true
in: path
description: user group's id
schema:
format: objectid
type: string
- name: customerId
required: true
in: query
description: customer's id
schema:
format: objectid
type: string
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/RemoveUserIdsFromGroupDto'
- $ref: '#/components/schemas/RemoveTimekeeperIdsFromGroupDto'
responses:
'200':
description: The updated user group
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserIdUserGroupDto'
- $ref: '#/components/schemas/TimekeeperIdUserGroupDto'
summary: Remove users from a user group
tags:
- User Groups
/api/v1/user-groups/by-external-id/{externalId}/users:
put:
description: 'mode is required. set (full-replace): add users in the payload and remove current members not in it (an empty payload clears the group). add: additive only, never removes. Identifiers that resolve to no user are skipped, not errors. Idempotent.'
operationId: UserGroupController_syncMembersByExternalId_v1
parameters:
- name: externalId
required: true
in: path
schema:
type: string
- name: customerId
required: true
in: query
description: The customer ID who this group belongs to
schema:
format: objectid
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SyncGroupMembershipDto'
responses:
'200':
description: The user IDs added and removed, plus identifiers that could not be resolved
content:
application/json:
schema:
$ref: '#/components/schemas/SyncGroupMembershipResponseDto'
summary: Sync a user group's membership by its external id
tags:
- User Groups
components:
schemas:
AddTimekeeperIdsToGroupDto:
type: object
properties:
kind:
description: The kind of IDs being used (timekeeper-id)
enum:
- timekeeper-id
type: string
ids:
description: Array of timekeeper IDs to add to the group
type: array
items:
type: string
required:
- kind
- ids
AddUserIdsToGroupDto:
type: object
properties:
kind:
description: The kind of IDs being used (user-id)
enum:
- user-id
type: string
ids:
description: Array of user IDs to add to the group
type: array
items:
type: string
format: objectid
required:
- kind
- ids
UserGroupDto:
type: object
properties:
_id:
type: string
description: The user group ID
format: objectid
customerId:
type: string
description: The customer ID that owns this user group
format: objectid
externalId:
type: string
description: The external ID of the user group for external system integration
name:
type: string
description: The name of the user group
description:
type:
- string
- 'null'
description: The description of the user group
updatedAt:
type: string
description: The date and time this user group was last updated
example: '2022-08-12T20:44:48Z'
format: iso-date-time
createdAt:
type: string
description: The date and time this user group was created
example: '2022-08-12T20:44:48Z'
format: iso-date-time
required:
- _id
- customerId
- externalId
- name
- updatedAt
- createdAt
RemoveTimekeeperIdsFromGroupDto:
type: object
properties:
kind:
description: The kind of IDs being used (timekeeper-id)
enum:
- timekeeper-id
type: string
ids:
description: Array of timekeeper IDs to remove from the group
type: array
items:
type: string
required:
- kind
- ids
UpdateUserGroupDto:
type: object
properties:
externalId:
type:
- string
- 'null'
description: The external ID for external system integration
name:
type:
- string
- 'null'
description: The name of the user group
description:
type:
- string
- 'null'
description: The description of the user group
SyncGroupMembershipResponseDto:
type: object
properties:
added:
description: user IDs added to the group
type: array
items:
type: string
removed:
description: user IDs removed from the group
type: array
items:
type: string
unresolved:
description: identifiers (email/externalId) that resolved to no user
type: array
items:
type: string
required:
- added
- removed
- unresolved
SyncGroupMembershipDto:
type: object
properties:
mode:
enum:
- add
- set
type: string
description: set (full-replace) or add (additive)
emails:
description: user emails to resolve to members
type: array
items:
type: string
externalIds:
description: user externalIds to resolve to members
type: array
items:
type: string
externalBillingSystemIds:
description: user external-billing-system identity values to resolve to members
type: array
items:
type: string
required:
- mode
TimekeeperIdUserGroupDto:
type: object
properties:
_id:
type: string
description: The user group ID
format: objectid
customerId:
type: string
description: The customer ID that owns this user group
format: objectid
externalId:
type: string
description: The external ID of the user group for external system integration
name:
type: string
description: The name of the user group
description:
type:
- string
- 'null'
description: The description of the user group
updatedAt:
type: string
description: The date and time this user group was last updated
example: '2022-08-12T20:44:48Z'
format: iso-date-time
createdAt:
type: string
description: The date and time this user group was created
example: '2022-08-12T20:44:48Z'
format: iso-date-time
required:
- _id
- customerId
- externalId
- name
- updatedAt
- createdAt
UserGroupUserResponseDto:
type: object
properties:
_id:
type: string
description: User ID
email:
type: string
description: User email address
firstName:
type: string
description: User first name
groupIds:
description: User group IDs
type: array
items:
type: string
jobTitle:
type: string
description: User job title
lastName:
type: string
description: User last name
nickname:
type: string
description: User nickname
required:
- _id
- email
- firstName
- lastName
UserIdUserGroupDto:
type: object
properties:
_id:
type: string
description: The user group ID
format: objectid
customerId:
type: string
description: The customer ID that owns this user group
format: objectid
externalId:
type: string
description: The external ID of the user group for external system integration
name:
type: string
description: The name of the user group
description:
type:
- string
- 'null'
description: The description of the user group
updatedAt:
type: string
description: The date and time this user group was last updated
example: '2022-08-12T20:44:48Z'
format: iso-date-time
createdAt:
type: string
description: The date and time this user group was created
example: '2022-08-12T20:44:48Z'
format: iso-date-time
required:
- _id
- customerId
- externalId
- name
- updatedAt
- createdAt
RemoveUserIdsFromGroupDto:
type: object
properties:
kind:
description: The kind of IDs being used (user-id)
enum:
- user-id
type: string
ids:
description: Array of user IDs to remove from the group
type: array
items:
type: string
format: objectid
required:
- kind
- ids
CreateUserGroupDto:
type: object
properties:
customerId:
type: string
description: The customer's id who this group is associated with
format: objectid
externalId:
type: string
description: The external ID for external system integration
name:
type: string
description: The name of the user group
description:
type:
- string
- 'null'
description: The description of the user group
required:
- customerId
- externalId
- name
UpsertUserGroupByExternalIdDto:
type: object
properties:
name:
type: string
description: The name of the user group
description:
type:
- string
- 'null'
description: The description of the user group
required:
- name
securitySchemes:
ApiBearerAuth:
scheme: bearer
bearerFormat: JWT
description: Enter access token
type: http
externalDocs:
description: Laurel API Documentation
url: https://developer.laurel.ai/