Get User Group

This endpoint allows you to retrieve information about specific user groups and list all user groups with optional filtering.

🔹 Endpoint Details

Get Single Group

GET /api/v1/user-groups/{id}

List Groups

GET /api/v1/user-groups

🔒 Authentication

Header	Required	Description
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Parameters

Path Parameters (Get Single Group)

Parameter	Type	Required	Description	Example
id	string (UUID)	Yes	Unique identifier of the user group	550e8400-e29b-41d4-a716-446655440000

Query Parameters (List Groups)

Parameter	Type	Required	Description	Default
page	number	No	Page number for pagination	1
limit	number	No	Items per page	20
search	string	No	Search in name and description	-
organizationId	string	No	Filter by organization ID	-

🧩 Request Examples

Get Single Group

curl -X GET "https://openapi.onlive.site/api/v1/user-groups/550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

List Groups with Filtering

curl -X GET "https://openapi.onlive.site/api/v1/user-groups?page=1&limit=10&search=sales" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📤 Response Format

Single Group Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Sales Team",
  "description": "Sales team members with access to product management",
  "externalId": "SALES_TEAM_01",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "extraFields": {
    "department": "Sales",
    "location": "New York",
    "allowedFeatures": [
      "product_management",
      "sales_reports"
    ]
  },
  "createdAt": "2025-05-22T10:30:00Z",
  "updatedAt": "2025-05-22T10:30:00Z"
}

List Response (200 OK)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Sales Team",
      "description": "Sales team members with access to product management",
      "externalId": "SALES_TEAM_01",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "extraFields": {
        "department": "Sales",
        "location": "New York",
        "allowedFeatures": [
          "product_management",
          "sales_reports"
        ]
      },
      "createdAt": "2025-05-22T10:30:00Z",
      "updatedAt": "2025-05-22T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10,
  "pages": 1
}

❌ Error Responses

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid or missing authorization credentials"
}

404 Not Found

{
  "statusCode": 404,
  "message": "User group not found"
}

📘 Notes

• All timestamps are in ISO 8601 format with UTC timezone
• The list endpoint supports pagination through page and limit parameters
• Search is case-insensitive and matches partial strings in both name and description
• Results are sorted by creation date in descending order (newest first)
• The organizationId filter is optional; by default, only groups in your organization are shown

✅ Common Use Cases

• 🔍 Group Lookup: Retrieve details of a specific group by ID
• 📊 Directory: List all groups in your organization
• 🔎 Search: Find groups by name or description
• 📱 Pagination: Handle large numbers of groups efficiently
• 🏢 Organization: Filter groups by organization ID

---