POST Workgroup

Provide a REST API endpoint to create a new Workgroup master record within the Incident Management (IM) module. The API enables the creation of Workgroup records, including configuration settings, SLA alert settings, and associated child entities such as Workgroup Locations.

Endpoint

This endpoint creates a new Workgroup record in the IM module. It allows authorized users, integrations, and automation tools to create Workgroup master data and related location mappings in a single transaction.

POST /API/v1/Master/IM/Workgroup

Endpoint Path Parameters

Parameter Name	Data Type	Required	Description	Example
masterName	string	Yes	Name of the master entity where you create the record. Fixed value: `Workgroup`.	Workgroup

Note: Before creating Workgroup record, system retrieves its metadata to review required fields, supported fields, payload structure, constraints, and applicable endpoints. GET /API/v1/Master/IM/Workgroup/metadata?sections=create,children.

Sample Request

The request body contains the Workgroup attributes and child entity information required to create a new Workgroup record. The system validates all submitted values against the Workgroup metadata configuration before creating the record.

{
  "Active": true,
  "Alternate_Workgroup_ID": null,
  "Is_Enable_CL": false,
  "Is_Enable_CM_And_CMDB": false,
  "Is_Enable_IM_And_PM": true,
  "Is_Notify_Workgroup_Owner_For_Incident": true,
  "Is_Default": false,
  "Is_Enable_Live_Agent_Transfer": true,
  "Is_Master_Workgroup": true,
  "Manager": "Carlos.Rivera",
  "Parent_ID": null,
  "Response_Alert_On_50_Percentage": true,
  "Response_Alert_On_75_Percentage": true,
  "Resolution_Alert_On_100_Percentage": true,
  "Resolution_Alert_On_50_Percentage": true,
  "Resolution_Alert_On_75_Percentage": true,
  "Response_Alert_On_100_Percentage": true,
  "Is_Enable_SR": true,
  "Instance": "IT",
  "Description": "wg Description",
  "Text": "wg1",
  "Location": null,
  "children": {
    "workgroup_locations": [
      {
        "Is_Default": true,
        "Location": "Bangalore"
      }
    ]
  }
}

Sample Request Body Fields

Field Name	Data Type	Description
Active	Boolean	Indicates whether the Workgroup is active.
Alternate_Workgroup_ID	String/Null	Reference to an alternate Workgroup.
Is_Enable_CL	Boolean	Enables Change Lifecycle functionality.
Is_Enable_CM_And_CMDB	Boolean	Enables Configuration Management and CMDB functionality.
Is_Enable_IM_And_PM	Boolean	Enables Incident Management and Problem Management functionality.
Is_Notify_Workgroup_Owner_For_Incident	Boolean	Sends notifications to the Workgroup Owner for incidents.
Is_Default	Boolean	Indicates whether the Workgroup is the default Workgroup.
Is_Enable_Live_Agent_Transfer	Boolean	Enables Live Agent Transfer functionality.
Is_Master_Workgroup	Boolean	Indicates whether the system designates the Workgroup as a Master Workgroup.
Manager	String	Workgroup Manager/User ID.
Parent_ID	String/Null	Parent Workgroup reference.
Response_Alert_On_50_Percentage	Boolean	Triggers a response SLA alert at 50% threshold.
Response_Alert_On_75_Percentage	Boolean	Triggers a response SLA alert at 75% threshold.
Response_Alert_On_100_Percentage	Boolean	Triggers a response SLA alert at 100% threshold.
Resolution_Alert_On_50_Percentage	Boolean	Triggers a resolution SLA alert at 50% threshold.
Resolution_Alert_On_75_Percentage	Boolean	Triggers a resolution SLA alert at 75% threshold.
Resolution_Alert_On_100_Percentage	Boolean	Triggers a resolution SLA alert at 100% threshold.
Is_Enable_SR	Boolean	Enables Service Request functionality.
Instance	String	Application instance associated with the Workgroup.
Description	String	Detailed description of the Workgroup.
Text	String	Workgroup name or display name.
Location	String/Null	Primary location associated with the Workgroup.
children.workgroup_locations	Array	Child collection containing associated Workgroup Locations.

Child Entity: workgroup_locations

Field Name	Data Type	Description
Is_Default	Boolean	Indicates whether the location is the default Workgroup location.
Location	String	Location associated with the Workgroup.

Note While creating a Default Workgroup by setting Is_Default: true, only one default Workgroup must exist, setting more than one will return error.

Sample Response

The response confirms that a new Workgroup has been successfully created. A successful operation returns the unique identifier of the newly created Workgroup along with a confirmation message.

{
  "message": "Workgroup created successfully.",
  "UID": 101
}

Success Response

The Workgroup record has been successfully created and stored in the system. The response returns the unique identifier of the newly created Workgroup for future reference.

Response: HTTP 201 Created

{
  "message": "Workgroup created successfully.",
  "UID": 101
}

Error Messages

400 Bad Request

The server could not process the request because the submitted payload is invalid or does not meet the required validation rules. Review the request body for missing mandatory fields, incorrect data types, or invalid values.

{
  "message": "Invalid request payload.",
  "errorCode": 400,
  "details": "One or more fields failed validation."
}

401 Forbidden

The system cannot authenticate the request because valid API credentials were not provided or have expired. Include a valid API key or authentication token in the request.

{
  "message": "Unauthorized access.",
  "errorCode": 401,
  "details": "Valid API credentials are required."
}

403 Forbidden

The authenticated user lacks the permissions to create Workgroup records. Contact the system administrator to get the required access rights.

{
  "message": "You do not have permission to create Workgroup records.",
  "errorCode": 403,
  "details": "The authenticated user lacks the required privileges to perform this operation."
}

Documentation Index