These endpoints are designed for read-oriented integration use cases — pulling call history into downstream reporting pipelines, surfacing live queue and agent metrics on custom dashboards, retrieving recordings for quality assurance workflows, and syncing agent and skill rosters with external systems.

All responses are returned as JSON unless otherwise specified. Requests are authenticated using a Service User bearer token scoped to CCaaS.

All API requests must include:

• HTTP Method — The request action (e.g. GET, POST)
• API URL — The endpoint where the request is sent
• Bearer/Auth API Token — Used to authenticate the request

Optionally, a request may include:

• Parameter Key(s) — Key-value identifiers used as a lookup filter in the request

📘

Good-to-Knows

1. FQDN (Fully Qualified Domain Name) refers to the CCaaS organizational hostname, domain, and top-level domain. Typically formatted as: [hostname].xima.cloud; where the hostname is the company assigned unique identifier, domain is xima, and the top-level domain is cloud.

For rate limiting rules and a full list of expected response statuses, see API Limits & Statuses.

Historical Call Data

Executes a saved historic report and returns the results as structured data.

This endpoint is useful for pulling time-bounded call activity into external systems, generating custom exports, or feeding downstream reporting pipelines.

The report to execute is identified by its report_id, which corresponds to a report configured within the CCaaS platform.

The request body defines the output format and any report-specific parameters such as the time window or agent filter.

Endpoint

POST /rest/api/v1/historic-data/{report_id}

Path Parameters

Headers

Request Body

Parameter Object

Each object in the parameters array contains a name and a value.

Report Timeframe

Request

POST /rest/api/v1/historic-data/{report_id} HTTP/1.1
Host: <hostname>.xima.cloud
Content-Type: application/json
Authorization: Bearer <api_bearer_token>

{
    "format": "JSON",
    "parameters": [
        {
            "name": "Report Timeframe",
            "value": {
                "type": "REPORT_TIMEFRAME",
                "formatted": "Tuesday, June 2, 2026 12:00:00 AM - Tuesday, June 2, 2026 11:59:59 PM",
                "start": "2026-06-02T00:00:00-06:00",
                "end": "2026-06-03T00:00:00-06:00"
            }
        },
        {
            "name": "Rows (Agent)",
            "value": {
                "type": "PBX_USERS",
                "pbxUsers": [
                    {
                        "key": "Agent_001(999)"
                    }
                ]
            }
        }
    ]
}

curl -L -X POST 'https://<hostname>.xima.cloud/rest/api/v1/historic-data/{report_id}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <api_bearer_token>' \
-d '{
    "format": "JSON",
    "parameters": [
        {
            "name": "Report Timeframe",
            "value": {
                "type": "REPORT_TIMEFRAME",
                "formatted": "Tuesday, June 2, 2026 12:00:00 AM - Tuesday, June 2, 2026 11:59:59 PM",
                "start": "2026-06-02T00:00:00-06:00",
                "end": "2026-06-03T00:00:00-06:00"
            }
        },
        {
            "name": "Rows (Agent)",
            "value": {
                "type": "PBX_USERS",
                "pbxUsers": [
                    {
                        "key": "Agent_001(999)"
                    }
                ]
            }
        }
    ]
}'

Response

Returns a JSON object containing the report results. The structure of the response varies based on the report type and the format specified in the request body.

Real-time Metrics Data

Returns a snapshot of current contact center metrics across queues, agents, and skills.

This endpoint is intended for live monitoring use cases such as wallboard displays, supervisor dashboards, or agent-facing widgets that surface queue depth, wait times, or agent availability in real time.

Endpoint

GET /rest/api/v1/realtime/metrics

Headers

Query Parameters

Request

GET /rest/api/v1/realtime/metrics HTTP/1.1
Host: <hostname>.xima.cloud
Content-Type: application/json
Authorization: Bearer <api_bearer_token>

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v1/realtime/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <api_bearer_token>'

Response

Returns a JSON object containing the current real-time metrics of the CCaaS tenant.

[
    {
        "metricId": "",
        "metricName": "",
        "categoryType": "",
        "categorySelection": [
            ...
            "",
            ...
        ]
    }
]

Real-time Metrics Subscription

A web-socket connection to subscribe to current contact center metrics across queues, agents, and skills.

This endpoint is intended for live monitoring use cases such as wallboard displays, supervisor dashboards, or agent-facing widgets that surface queue depth, wait times, or agent availability in real time.

Endpoint

wss /rest/api/v1/realtime-metric-subscription

Query Parameters

Request

wss://<hostname>.xima.cloud/rest/api/v1/realtime-metric-subscription?id=<metric_id>&auth_token=<api_bearer_token>

Response

Returns a Handshake Details and JSON objects containing the subscribed real-time metrics of the CCaaS tenant.

Recording Data

Retrieves a list of call recordings within a specified time range.

Each record in the response includes metadata about the recording — such as the involved parties, call direction, associated skill, assigned agent, and file size — but does not include the audio content itself.

To retrieve the audio for a specific recording, use the Audio Data endpoint with the returned recordingKey.

Endpoint

GET /rest/api/v2/recordings

Headers

Query Parameters

Request

GET /rest/api/v2/recordings?startTime={start_time}&endTime={end_time} HTTP/1.1
Host: <hostname>.xima.cloud
Content-Type: application/json
Authorization: Bearer <api_bearer_token>

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v2/recordings?startTime={start_time}&endTime={end_time}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <api_bearer_token>'

Response

Returns an array of recording metadata objects matching the specified time range.

{
  ...
  {
    "recordingKey": "",
    "callKey": "",
    "startTime": 123456789,
    "duration": 123456,
    "size": 123456789,
    "eventId": 123456,
    "recordingSystemId": 0,
    "status": "",
    "callingParty": "",
    "receivingParty": "",
    "tenantName": "",
    "tagData": "",
    "callDirection": "",
    "skill": "",
    "agent": ""
  }
  ...
}

Audio Data

Retrieves the audio file for a specific call recording.

The recordingKey required for this request is returned as part of the Recording Data response.

Audio is returned in OGG format.

⚠️

Audio files must be requested one at a time

Though the metadata of many recordings can be retrieved at once, this API request must request recordings one at a time. Bulk audio exports are not supported.

Endpoint

GET /rest/api/v2/recordings/{hostname}/{recording_key}/audio

Path Parameters

Headers

Request

GET /rest/api/v2/recordings/{tenant_name}/{recording_key}/audio HTTP/1.1
Host: <hostname>.xima.cloud
Content-Type: audio/ogg
Authorization: Bearer <api_bearer_token>

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v2/recordings/{tenant_name}/{recording_key}/audio' \
-H 'Content-Type: audio/ogg' \
-H 'Authorization: Bearer <api_bearer_token>'

Response

Returns the raw audio file as an OGG-encoded binary stream. The Content-Type of the response is audio/ogg.

Agent Data

Returns a list of all agents configured in CCaaS, including each agent's identifier, display name, type, and associated email address.

This endpoint is commonly used to populate agent selectors in external tools, sync agent rosters with workforce management systems, or validate agent identifiers before constructing requests to other endpoints.

Endpoint

GET /rest/api/v1/agents

Headers

Request

GET /rest/api/v1/agents HTTP/1.1
Host: <hostname>.xima.cloud
Content-Type: application/json
Authorization: Bearer <api_bearer_token>

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v1/agents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <api_bearer_token>'

Response

Returns a JSON object containing an array of agent records.

{
  "agents": {
    ...
    {
      "agent": "",
      "type": "",
      "email": ""
    },
    ...
  }
}

Skill Data

Returns a list of all skills (queues) configured in CCaaS.

Skills in Xima represent routing queues that direct incoming interactions to appropriate agents.

This endpoint is useful for populating skill-based filters in reporting integrations, synchronizing queue configurations with external systems, or resolving skill names from identifiers returned by other endpoints.

Endpoint

GET /rest/api/v1/skills

Headers

Request

GET /rest/api/v1/skills HTTP/1.1
Host: <hostname>.xima.cloud
Content-Type: application/json
Authorization: Bearer <api_bearer_token>

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v1/skills' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <api_bearer_token>'

Response

Returns a JSON object containing an array of skill records.

{
  "skills": {
    ...
    {
      "id": "",
      "name": ""
    },
    ...
  }
}