Update User Group

This endpoint allows you to update an existing user group's information. Only provided fields will be modified, while others remain unchanged.

🔹 Endpoint Details

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

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Structure

Path Parameters

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

Request Body Properties

Field	Type	Required	Description	Example
name	string	No	New name for the user group (min length: 1)	"Global Sales Team"
description	string	No	New description of the group's purpose	"International sales team"
externalId	string	No	New external identifier	"SALES_TEAM_01"
extraFields	object	No	Updated custom fields	See example below

🧩 Request Example

curl -X PUT "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" \
-d '{
  "name": "Global Sales Team",
  "description": "International sales team with product management access",
  "extraFields": {
    "department": "Sales",
    "location": "Global",
    "allowedFeatures": [
      "product_management",
      "sales_reports",
      "international_pricing"
    ]
  }
}'

📤 Response Format

Successful Response (200 OK)

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

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "name",
      "message": "name must not be empty"
    }
  ]
}

401 Unauthorized

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

404 Not Found

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

409 Conflict

{
  "statusCode": 409,
  "message": "A user group with this externalId already exists"
}

📘 Notes

• Only include fields you want to update in the request body
• Omitted fields retain their current values
• The extraFields object is replaced entirely when provided, not merged
• To remove an optional field, set its value to null
• The response includes all fields of the group, including unchanged ones
• The updatedAt timestamp automatically reflects the latest change
• You can only update groups within your organization

✅ Common Use Cases

• 🔄 Rename Group: Update the group's name or description
• 🌍 Location Change: Update office or department location
• 🔐 Permission Updates: Modify allowed features or access rights
• 🔗 System Integration: Update external system mappings
• 📊 Metadata Changes: Update custom fields for tracking purposes

---