---
title: "GET Workgroup"
slug: "get-workgroup"
updated: 2026-08-06T15:05:08Z
published: 2026-08-06T15:05:08Z
canonical: "help.symphonysummitai.com/get-workgroup"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.symphonysummitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET Workgroup

The IT Admin Agent leverages the Retrieve Workgroup List and Details API to automate Workgroup discovery, monitoring, and configuration validation within the Apex Platform. This enables zero-touch operations and improves administrative efficiency.

The API supports the following operations:

- [Retrieve Workgroup Details](/apex/docs/get-workgroup#retrieve-workgroup-details)
- [Retrieve List of Workgroups](/apex/docs/get-workgroup#retrieve-list-of-workgroups)

## Retrieve Workgroup Details

External systems consume this API, including automation tools, AI agents, and integration services.

This endpoint retrieves the details of a specific Workgroup using its unique identifier (`UID`). Integrations, automation tools, and AI agents commonly use it to access Workgroup configuration and reference data.

### Endpoint

```http
GET /API/v1/Master/IM/Workgroup/{UID}
```

| Component | Value | Description |
| --- | --- | --- |
| **HTTP Method** | GET | Retrieves data from the server. This is a read-only operation and does not create, update, or delete records. |
| **API** | API | Stands for **Application Programming Interface**. It provides a standard way for applications to communicate with the system and exchange data. |
| **Version** | v1 | Indicates Version 1 of the API. Versioning helps maintain compatibility as we introduce new API versions. |
| **Resource Group** | Master | Refers to the Master Data module, which contains reusable reference and configuration data. |
| **Module** | IM | Stands for **Incident Management**. It identifies that the requested master data belongs to the Incident Management module. |
| **Resource** | Workgroup | Specifies the Workgroup master resource to retrieve. |
| **Record Identifier** | `{UID}` | Identifies the Workgroup record to retrieve. |

### Endpoint Path Parameters

| Parameter | Type | Location | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `UID` | String or integer | Path | Yes | Unique identifier of the Workgroup record to retrieve. | `101` |

### Request Headers

```json
{
  "Accept": "application/json",
  "X-Api-Key": "{API_KEY}"
}
```

| Header | Value | Required | Description |
| --- | --- | --- | --- |
| Accept | `application/json` | Yes | Requests the API to return the response in JSON format. |
| X-Api-Key | `{API_KEY}` | Yes | API key used to authenticate and approve the caller. |

### Sample Request

The request sends a GET call with a valid Workgroup UID and API credentials. Upon successful validation, the system fetches and returns the corresponding Workgroup record.

```bash
curl --location '{host}/API/v1/Master/IM/Workgroup/101' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {API_KEY}'
```

Replace `101` with the required Workgroup UID, `{API_KEY}` with a valid API key, and `{host}` with the appropriate server address.

- Given a valid Workgroup UID or Value,
- The system sends a GET request with the UID or Value.
- The API returns the details of the specified Workgroup with HTTP `200 OK`.

### Sample Response

The response returns the details of the requested Workgroup along with execution statistics. A successful request returns HTTP `200 OK` and includes the Workgroup UID and name in the response payload.

```json
{
  "message": "1 Record(s) found.",
  "data": {
    "workgroup": [
      {
        "UID": 101,
        "Text": "Infrastructure Support"
      }
    ]
  },
  "executionTime": 0.10
}
```

### Response Fields

| Field | Type | Example Value | Description |
| --- | --- | --- | --- |
| message | String | `"1 Record(s) found."` | Summarizes the number of Workgroup records returned. |
| data | Object | `{...}` | Contains the response data. |
| data.workgroup | Array | `[{...}]` | Contains the Workgroup record returned by the API. |
| UID | Integer | `101` | Unique identifier of the Workgroup record. |
| Text | String | `"Infrastructure Support"` | Display name of the Workgroup. |
| executionTime | Number | `0.10` | Time taken to execute the request, as reported by the API. |

### Business Use Cases

| Scenario | Resolution |
| --- | --- |
| An integration receives a Workgroup UID in an Incident payload and must verify the corresponding Workgroup before processing the Incident. | Retrieve the Workgroup using its `UID`. Confirm that the response contains the expected `Text` value, then use the verified mapping for routing, synchronization, or reporting. |
| An AI agent detects a failed Workgroup assignment and must determine whether the stored mapping is still valid. | Retrieve the affected Workgroup by `UID` and compare the returned identifier and name with the mapping stored in the consuming system. If the record is missing or the name has changed, flag the mapping for correction before retrying the assignment. |

### Expected Result

- Returns HTTP `200 OK` for a successful request.
- Returns the Workgroup record that matches the specified `UID`.
- Returns the Workgroup identifier and display name.
- Returns execution statistics when supported by the endpoint.

## Retrieve List of Workgroups

External systems consume this API, including automation tools, AI agents, and integration services.

This endpoint retrieves all available Workgroup records configured within the IM module. It supports automation, reporting, monitoring, migration, and integration scenarios that require Workgroup master data.

### Endpoint

```http
GET /API/v1/Master/IM/Workgroup
```

| Component | Value | Description |
| --- | --- | --- |
| **HTTP Method** | GET | Retrieves data from the server. This is a read-only operation and does not create, update, or delete records. |
| **API** | API | Stands for **Application Programming Interface**. |
| **Version** | v1 | Indicates Version 1 of the API. |
| **Resource Group** | Master | Refers to the Master Data module. |
| **Module** | IM | Identifies the Incident Management module. |
| **Resource** | Workgroup | Specifies the Workgroup master resource to retrieve. |

### Endpoint Parameters

This endpoint does not require any path or query parameters.

### Request Headers

```json
{
  "Accept": "application/json",
  "X-Api-Key": "{API_KEY}"
}
```

| Header | Value | Required | Description |
| --- | --- | --- | --- |
| Accept | `application/json` | Yes | Requests the API to return the response in JSON format. |
| X-Api-Key | `{API_KEY}` | Yes | API key used to authenticate and authorize the caller. |

### Sample Request

The request sends a GET call with valid API credentials to retrieve the complete list of Workgroups. This operation requires no path or query parameters.

```bash
curl --location '{host}/API/v1/Master/IM/Workgroup' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {API_KEY}'
```

Replace `{API_KEY}` with a valid API key and `{host}` with the appropriate server address.

- Given that the GET Workgroup List API is available,
- The system sends a valid GET request.
- The API returns all available Workgroups with the expected response structure and HTTP `200 OK`.

### Sample Response

The response returns a collection of Workgroup records along with the total number of records found and execution time.

```json
{
  "message": "2 Record(s) found.",
  "data": {
    "workgroup": [
      {
        "UID": 101,
        "Text": "Infrastructure Support"
      },
      {
        "UID": 102,
        "Text": "Application Services"
      }
    ]
  },
  "executionTime": 0.12
}
```

Given that the API returns a successful response, the response payload conforms to the defined API schema and includes the following fields:

- `message`
- `data`
- `workgroup`
- `UID`
- `Text`
- `executionTime`

### Response Schema

```json
{
  "message": "string",
  "data": {
    "workgroup": [
      {
        "UID": "integer",
        "Text": "string"
      }
    ]
  },
  "executionTime": "number"
}
```

### Response Fields

| Field | Type | Example Value | Description |
| --- | --- | --- | --- |
| message | String | `"2 Record(s) found."` | Summarizes the number of Workgroup records returned. |
| data | Object | `{...}` | Contains the response data. |
| data.workgroup | Array | `[{...}]` | Contains the Workgroup records returned by the API. |
| UID | Integer | `101` | Unique identifier of a Workgroup record. |
| Text | String | `"Infrastructure Support"` | Display name of a Workgroup record. |
| executionTime | Number | `0.12` | Time taken to execute the request, as reported by the API. |

### Business Use Cases

| Scenario | Resolution |
| --- | --- |
| An external system maintains Workgroup mappings used for Incident routing, synchronization, automated workflows, and reporting. | Retrieve the complete Workgroup list and compare each returned `UID` and `Text` value with the external mapping table. Add newly created Workgroups, update renamed records, and flag mappings whose Workgroup no longer appears in the API response. This prevents routing failures and the use of obsolete Workgroup identifiers. |
| Migrate Workgroup data from another system to the Apex Platform. | Retrieve all available target Workgroups, compare their `Text` values with the Workgroup names in the source system, map each source value to the corresponding target `UID`, document unmatched records, and resolve duplicate or ambiguous names before migration. Use the validated identifiers in migration payloads to prevent the system from assigning Incidents to the wrong Workgroup. |

### Expected Result

- Returns HTTP `200 OK`.
- Returns all available Workgroup records configured within the IM module.
- Returns the unique identifier and display name of each Workgroup.
- Returns the record count and execution time when supported by the endpoint.

## Error Messages for Record Details and List

### 401 Unauthorized

The system cannot authenticate the request because valid API credentials were not provided or have expired.

The following request does not include the required `X-Api-Key` header:

```bash
curl --location '{host}/API/v1/Master/IM/Workgroup' \
  --request GET \
  --header 'Accept: application/json'
```

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

### 403 Forbidden

The caller has authenticated, but the associated user, agent, or service account does not have permission to access Workgroup records.

The following is Valid API Key Without Workgroup Access:

```bash
curl --location '{host}/API/v1/Master/IM/Workgroup' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {VALID_API_KEY_WITHOUT_WORKGROUP_ACCESS}'
```

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

### 404 Not Found

The specified Workgroup record does not exist or is unavailable in the system. This response can also occur when the endpoint path is incorrect.

The following request attempts to retrieve an Workgroup record with the record ID `9999`:

```bash
curl --location '{host}/API/v1/Master/IM/Workgroup/9999' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {API_KEY}'
```

```json
{
  "message": "Workgroup record not found.",
  "errorCode": 404,
  "details": "No Workgroup record was found for the specified UID."
}
```