---
title: "GET Tenant"
slug: "get-tenant"
status: "update"
updated: 2026-10-23T05:42:34Z
published: 2026-10-23T05:42:34Z
canonical: "help.symphonysummitai.com/get-tenant"
---

> ## 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 Tenant

The IT Admin Agent leverages the Retrieve Tenant/Instance List and Details API to automate tenant 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 Tenant Details](/apex/docs/get-tenant#retrieve-tenant-details)
- [Retrieve List of Tenants](/apex/docs/get-tenant#retrieve-list-of-tenants)

## Retrieve Tenant Details

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

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

### Endpoint

```http
GET /API/v1/Master/IM/Instance/{recordId}?includeChildren=true
```

| 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 for 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** | Instance | Specifies the Tenant/Instance master resource to retrieve. |
| **Record Identifier** | `{recordId}` | Identifies the Tenant/Instance record to retrieve. |
| **Query Option** | `includeChildren` | An optional Boolean parameter that determines whether the response includes only the selected Tenant/Instance or also includes its related child configurations. Set it to true to include child records. |

> [!NOTE]
> Note
> 
> In this endpoint /API/v1/Master/IM/Instance/ - module can change according to the requirement IM, SR, etc..

### Endpoint Parameters

The path parameter identifies the Tenant/Instance using `recordId`, while `includeChildren` controls whether the response includes child configurations.

| Parameter | Type | Location | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `recordId` | String or integer | Path | Yes | Unique identifier of the Instance record to retrieve. | `1001` |
| `includeChildren` | Boolean | Query | No | Specifies whether the response includes child configurations associated with the Instance. Set it to `true` to request the complete child configuration. | `true` |

### 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 with `includeChildren=true`

The request sends a GET call with a valid Tenant/Instance identifier and API credentials. When requested with `includeChildren=true`, the response includes associated child configurations and related entities.

```bash
curl --location '{host}/API/v1/Master/IM/Instance/1001?includeChildren=true' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: {API_KEY}'
```

Replace `1001` with the Tenant/Instance record ID. Replace `{API_KEY}` with a valid API key. Replace `{host}` with the appropriate server address when calling the API from another environment.

### Behavior When `includeChildren=true`

When `includeChildren=true`:

- The system returns the full hierarchical structure.
- The response includes sub-configurations, dependent entities, and modules when they are available for the requested Tenant/Instance.

#### Example Request

```http
GET /API/v1/Master/IM/Instance/1001?includeChildren=true
```

#### Illustrative Response with Children

```json
{
  "message": "1 Record(s) found.",
  "data": {
    "instance": [
      {
        "UID": 1001,
        "Text": "Information Technology",
        "children": [
          {
            "UID": 2001,
            "Text": "Service Desk"
          },
          {
            "UID": 2002,
            "Text": "Infrastructure Support"
          }
        ]
      }
    ]
  },
  "executionTime": 0.10
}
```

### Behavior When Omitting `includeChildren`

Because `includeChildren` is optional, the request can omit it and this is as good as `includeChildren=false`.

```http
GET /API/v1/Master/IM/Instance/1001
```

If the request omits the parameter, the API uses its configured default behavior. Confirm the implemented default before stating that omission equals either `true` or `false`.

### Sample Response

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

```json
{
  "message": "1 Record(s) found.",
  "data": {
    "instance": [
      {
        "UID": 2,
        "Text": "Information Technology"
      }
    ]
  },
  "executionTime": 0.10
}
```

**Note:** The original response retains above. Child fields are not visible in this sample payload.

### Response Fields

| Field | Type | Example Value | Description |
| --- | --- | --- | --- |
| message | String | `"1 Record(s) found."` | Summarizes the number of records returned by the request. |
| data | Object | `{...}` | Contains the response data. |
| data.instance | Array | `[{...}]` | Contains the Tenant/Instance records returned by the API. |
| UID | Integer | `2` | Unique identifier of the Tenant/Instance record. |
| Text | String | `"Information Technology"` | Display name of the Tenant/Instance. |
| executionTime | Number | `0.10` | Time taken to execute the request, as reported by the API. |
| children | Array | `[{...}]` | Contains child configurations when requested and returned by the API. This field is illustrative because it's not present in the original sample response. |

### Business Use Cases

| Scenario | Resolution |
| --- | --- |
| An administrator plans to change or deactivate a Tenant/Instance, and an AI agent must identify the dependent configurations that the change would affect. | Call the endpoint with `includeChildren=true` to retrieve the Tenant/Instance and its complete child hierarchy. The AI agent inspects the returned child configurations to identify dependent Workgroups, modules, sub-configurations, or related entities. It then reports the affected dependencies, identifies child records that may require reassignment, and warns the administrator before modifying or deactivating the Tenant/Instance. |
| An integration receives a Tenant/Instance ID and needs to verify the record or retrieve its display name, but it does not require the complete child hierarchy. | Call the endpoint without the `includeChildren` query parameter. For example: `GET /API/v1/Master/IM/Instance/1001`. The API uses its configured default behavior and returns the Tenant/Instance information defined for an omitted parameter. The integration can use the returned identifier and display name to check a stored mapping, enrich a report, synchronize reference data, or confirm that the Tenant/Instance exists. The integration must not assume that the API includes or excludes child configurations unless the API specification confirms the default behavior of `includeChildren`. |

### Expected Result

- Returns HTTP `200 OK` for a successful request.
- Returns the Tenant/Instance record that matches the specified `recordId`.
- Returns the Tenant/Instance identifier and display name.
- When `includeChildren=true`, returns available child configurations and related entities supported by the endpoint.
- When `includeChildren=false`, returns the basic Tenant/Instance data without the complete child hierarchy.

## Retrieve List of Tenants

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

This endpoint retrieves all available Tenant/Instance records configured within the IM module. It supports discovery, reporting, monitoring, and integration scenarios requiring tenant master data.

### Endpoint

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

| 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** | Instance | Specifies the Tenant/Instance 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 approve the caller. |

### Sample Request

The request sends a GET call with valid API credentials to retrieve the complete list of Tenant/Instance records. This operation does not require any path or query parameters.

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

Replace the masked API key with a valid API key. Replace `{host}` with the appropriate server address when calling the API from another environment.

### Sample Response

The response returns a collection of Tenant/Instance records available in the system. A successful request returns HTTP `200 OK` and includes the list of tenants along with the corresponding identifiers and names.

```json
{
  "message": "2 Record(s) found.",
  "data": {
    "instance": [
      {
        "UID": 2,
        "Text": "Information Technology"
      },
      {
        "UID": 3,
        "Text": "Human Resources"
      }
    ]
  }
}
```

### Response Fields

| Field | Type | Example Value | Description |
| --- | --- | --- | --- |
| message | String | `"2 Record(s) found."` | Summarizes the number of Tenant/Instance records returned. |
| data | Object | `{...}` | Contains the response data. |
| data.instance | Array | `[{...}]` | Contains the Tenant/Instance records returned by the API. |
| UID | Integer | `2` | Unique identifier of a Tenant/Instance record. |
| Text | String | `"Information Technology"` | Display name of a Tenant/Instance record. |

### Business Use Cases

| Scenario | Resolution |
| --- | --- |
| An external system maintains Tenant/Instance mappings used by integrations, automated workflows, and reporting processes. | Retrieve the complete Tenant/Instance list and compare each returned `UID` and `Text` value with the external system’s mapping table. Add newly created records, update renamed records, and flag mappings whose Tenant/Instance no longer appears in the API response. This prevents integrations from using outdated identifiers or displaying incorrect Tenant/Instance names. |
| Migrating Tenant/Instance data from another system to the Apex Platform. | Retrieve all available target Tenant/Instance records and compare their `Text` values with the Tenant/Instance names in the source system. Map each source value to the corresponding target `UID`, document records that do not have a match, and resolve duplicate or ambiguous names before migration. Use the validated identifiers in the migration payload to prevent assigning records to the wrong Tenant/Instance. |

### Expected Result

- Returns HTTP `200 OK`.
- Returns all available Tenant/Instance records configured within the IM module.
- Returns the unique identifier and display name of each Tenant/Instance record.

## Error Messages

### 401 Unauthorized

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

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

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

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

### 403 Forbidden

The authenticated user does not have the required permissions to access Tenant/Instance records. Contact the system administrator to get the required access rights.

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

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

### 404 Not Found

The specified Tenant/Instance record does not exist or is unavailable in the system. Verify the provided `recordId` and ensure the record exists before submitting the request again.

The following request attempts to retrieve a Tenant/Instance with the record ID 9999:

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

```json
{
  "message": "Tenant/Instance record not found.",
  "errorCode": 404,
  "details": "No Tenant/Instance record was found for the specified identifier."
}
```