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

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

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.

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

{
  "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.

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

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

Illustrative Response with Children

{
  "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.

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.

{
  "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`.

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

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

{
  "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.

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.

{
  "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.

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:

curl --location '{host}/API/v1/Master/IM/Instance' \
--request GET \
--header 'Accept: application/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.

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

{
  "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:

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

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

Documentation Index

GET Tenant

Retrieve Tenant Details

Endpoint

Endpoint Parameters

Request Headers

Sample Request with includeChildren=true

Behavior When includeChildren=true

Example Request

Illustrative Response with Children

Behavior When Omitting includeChildren

Sample Response

Response Fields

Business Use Cases

Expected Result

Retrieve List of Tenants

Endpoint

Endpoint Parameters

Request Headers

Sample Request

Sample Response

Response Fields

Business Use Cases

Expected Result

Error Messages

401 Unauthorized

403 Forbidden

404 Not Found

Sample Request with `includeChildren=true`

Behavior When `includeChildren=true`

Behavior When Omitting `includeChildren`