Administrative Audit Log APIs

The Administrative Audit Log APIs provide a forensic trail of configuration changes and sensitive actions performed within the RingCentral CX Voice platform. Unlike standard reporting APIs which aggregate performance metrics, the Audit Log API is a specialized governance tool. It allows organizations to verify compliance, investigate unauthorized changes, and maintain a high degree of accountability across administrative user sessions.

Governance and Oversight

Audit logs are critical for organizations requiring rigorous change management protocols. This API provides the transparency needed to answer "who changed what and when" regarding the platform's configuration.

Use Cases for Administrative Auditing

• Compliance and Security: Maintain an immutable record of system changes for regulatory requirements (e.g., PCI, HIPAA, or internal security audits).
• Change Management: Identify the precise origin of configuration changes that may have impacted contact center operations.
• Forensic Investigation: Track administrative user activity, including simulated sessions, to investigate suspicious or erroneous system modifications.

Historical vs Real Time Audit Scope

The Audit API is designed for the retrieval of historical change records. It is not intended for real-time monitoring or alerting. The system logs administrative events as they occur, making them available for retrieval 5 minutes after the action is finalized.

Required App Permissions (Scopes)

Access to the administrative audit trail is governed by OAuth Scopes and specific RingCX Admin Permissions. These settings ensure that forensic data is only accessible to authorized applications and users.

1. Configure OAuth Scopes

To successfully exchange a JWT for an access token using your client credentials, your application must be configured with the following permission in the Developer Portal:

• ReadAccounts: Required to validate the account context and complete the authentication flow.

For a detailed walkthrough on exchanging your JWT for an access token, please refer to the RingCentral Authentication Guide.

2. Enable RingCX Admin Access

In addition to app scopes, the user authenticating the app must have the specific Audit log access permission enabled within the RingCX Admin portal. Without this, the API will fail to authorize the request.

To enable this:

1. Log in to RingCX Admin.
2. Navigate to Users > Administrators.
3. Select the target user and ensure the Audit log access box is checked.

[!WARNING] If the application has the correct scopes but the user lacks this platform permission, the API will return the following error:

{
    "errorCode": "access.denied.exception",
    "generalMessage": "You do not have permission to access this resource",
    "details": "",
    "requestUri": "/api/v1/admin/auditLogs/search - PUT",
    "timestamp": <TIMESTAMP>
}

Important Technical Constraints

When querying the Audit Log Search endpoint, developers must adhere to these strict requirements:

• Mandatory Account Context: The accountId is a required field in the request body. It constrains the search to a specific sub-account to maintain data isolation.
• ISO-8601 Offset Requirement: Time parameters (startDateTime and endDateTime) must be formatted using ISO-8601 with an explicit UTC offset. The "Z" (Zulu) suffix is unsupported and will result in a request failure.
  • Accepted Format: 2025-11-20T00:00:00.000-08:00
  • Unsupported Format: 2025-11-20T00:00:00.000Z
• Audit Action Categorization: Administrative events are classified into three primary action types: CREATE (entity creation), UPDATE (modification of existing settings), and DELETE (removal of system entities).

Audit Log Discovery

Before searching, you may use the Discovery API to identify which system entities (such as Agents, Gates, or Queues) are eligible for auditing. The name values returned here are used to populate the searchEntities filter in your search requests.

GET https://ringcx.ringcentral.com/voice/api/v1/admin/auditLogs/auditable

Response Object

Audit Log Search

The Search API serves as the primary extraction point for audit records. It allows you to reconstruct the history of administrative tasks by filtering for specific timeframes, action types, or individual actors.

PUT https://ringcx.ringcentral.com/voice/api/v1/admin/auditLogs/search

Request Body

Example Request:

{
  "accountId": "12345",
  "auditActions": ["UPDATE", "DELETE"],
  "startDateTime": "2025-11-20T00:00:00.000-08:00",
  "endDateTime": "2025-12-03T23:59:00.228-08:00",
  "ascOrDesc": "DESCENDING"
}

Audit Log Response Details

The Audit Log API tracks administrative changes across the platform. The actionType field identifies the nature of the event:

• CREATE: A new entity (such as an Agent or Campaign) was added to the system.
• UPDATE: An existing entity was modified. These records include an auditLogResultList detailing specific field changes.
• DELETE: An entity was removed from the system.

The response object provides a chronological trail of administrative actions. Each record in the results array contains the following key attributes:

auditLogResultList Object Structure

For UPDATE actions, the auditLogResultList array details precisely which settings were altered:

• attributeName: The internal name of the setting that was changed (e.g., gatePriority).
• originalValue: The value of the setting before the update.
• newValue: The updated value of the setting.
• classType: The full Java class path of the entity being modified.

Example Response JSON

Below is an example output from the audit log search showing a configuration UPDATE to an existing Gate object.

[
    {
        "id": "00000000-0000-0000-0000-000000000000",
        "authUser": {
            "sourceId": "0.0.0.0",
            "firstName": "Admin",
            "lastName": "User",
            "userName": "[email protected]",
            "userId": "00000",
            "fullJson": null,
            "simulatedByUserId": null,
            "simulatedByUserName": null,
            "simulatedFromIP": null
        },
        "createTime": 1111111111111,
        "auditLogResultList": [
            {
                "attributeName": "gatePriority",
                "originalValue": "0",
                "newValue": "1",
                "classType": "com.connectfirst.api.model.intelliqueue_globalcatalog.acd.Gate"
            }
        ],
        "auditedClass": "com.connectfirst.api.model.intelliqueue_globalcatalog.acd.Gate",
        "auditedEntityId": "000000",
        "auditedEntityDescription": "Example Entity Name",
        "actionType": "UPDATE",
        "affectedEntityJson": null,
        "accountId": "00000000",
        "createTimeAsDateTime": "2026-01-13T00:00:00.000+0000",
        "_class": "com.connectfirst.api.model.documents.AuditLog"
    }
]

Supported elements

To help developers navigate the audit logs, the following list represents the system elements that can be tracked. These values correspond to the final segment of the auditedClass string found in the API response.

Implementation Strategy

To build a reliable synchronization service (e.g., exporting audit logs to an external security database), developers should implement a "Sliding Window" polling strategy.

Recommended Polling Pattern

To ensure 100% data integrity and account for the propagation delay, we recommend retrieving audit logs in 15-minute intervals, initiated 5 minutes after the window closes.

Example Schedule:

Sample Implementation (Python)

The following example demonstrates how to poll the API and persist the results into a local SQLite database for downstream reporting.

import requests
import datetime
import sqlite3
import json

# Configuration
BASE_URL = "https://ringcx.ringcentral.com/voice/api/v1/admin/auditLogs/search"
ACCOUNT_ID = "12345"

def save_to_database(logs):
    """Simulates persisting audit logs to an SQL database."""
    conn = sqlite3.connect('audit_trail.db')
    cursor = conn.cursor()

    # Create table if it doesn't exist
    cursor.execute('''
        CREATE TABLE IF NOT EXISTS logs 
        (id TEXT PRIMARY KEY, action TEXT, user TEXT, timestamp TEXT, raw_json TEXT)
    ''')

    for entry in logs:
        cursor.execute('''
            INSERT OR IGNORE INTO logs (id, action, user, timestamp, raw_json)
            VALUES (?, ?, ?, ?, ?)
        ''', (
            entry.get('id'),
            entry.get('actionType'),
            entry['authUser'].get('userName'),
            entry.get('createTimeAsDateTime'),
            json.dumps(entry)
        ))

    conn.commit()
    conn.close()
    print(f"Successfully synced {len(logs)} entries.")

def sync_audit_logs():
    # 1. Define the 15-minute window with a 5-minute delay
    now = datetime.datetime.now(datetime.timezone.utc)
    end_time = now - datetime.timedelta(minutes=5)
    start_time = end_time - datetime.timedelta(minutes=15)

    payload = {
        "accountId": ACCOUNT_ID,
        "startDateTimeAsUnix": int(start_time.timestamp() * 1000),
        "endDateTimeAsUnix": int(end_time.timestamp() * 1000),
        "ascOrDesc": "ASCENDING"
    }

    headers = {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
    }

    # 2. Invoke the API
    response = requests.put(BASE_URL, json=payload, headers=headers)

    if response.status_code == 200:
        logs = response.json()
        # 3. Persist logs to database
        save_to_database(logs)
    else:
        print(f"Error fetching logs: {response.status_code}")

if __name__ == "__main__":
    sync_audit_logs()