3CX REST API (XAPI) Endpoint Guide for Configuration

Updated on October 2, 2026

5 min read

This document provides a complete guide to the REST API endpoint specification for configuring the 3CX PBX system. This API lets you manage authentication, departments, users, system extensions, and version checks programmatically.

🔗 Base URL & Environment #

All API requests are sent to the FQDN (Fully Qualified Domain Name) of your 3CX instance:

https://{{PBX_FQDN}}

📑 Table of Contents #

Authentication / Authorization
Departments Management
Users Management
System & Utilities
Active Calls
Reports & Call History
Trunk & Routing
Phonebook & Contacts
System Settings & Utility
Event Logs

1. Authentication / Authorization #

Endpoint: Get Token #

Implements authentication and returns an access_token based on the corresponding role.

HTTP Method: POST
URL Endpoint: https://{{PBX_FQDN}}/connect/token
Authentication: Required (Basic Authentication)
Content-Type: application/x-www-form-urlencoded

Request Body #

Parameter	Type	Description
`client_id`	String (Required)	Fixed value: `server_principal_id`.
`client_secret`	String (Required)	The secret key obtained after setting up the Service Principal.
`grant_type`	String (Required)	Fixed value: `client_credentials`.

Example Response (200 OK) #

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "ACCESS_TOKEN",
  "refresh_token": null
}

Error Response (401 Unauthorized) #

{
  "error": "unauthorized",
  "error_description": "The request requires valid user authentication."
}

💡 BetterDocs Tip: This access_token is valid for 3600 seconds (1 hour). You must re-authenticate once the token expires.

2. Departments Management #

Endpoint: Check if Department Exists #

Checks whether a department with a given name is already registered in 3CX, to avoid creating a duplicate.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq '{Department_Name}'
Example URL: https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq '3CX Test'

Example Response – If Department Is Found (200 OK) #

{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
  "value": [
    {
      "Name": "DEFAULT",
      "IsDefault": true,
      "HasMembers": true,
      "Number": "GRP0000",
      "Id": 28
    }
  ]
}

Endpoint: Create a Department #

Creates a new department in 3CX with language, timezone, and service number range configuration.

HTTP Method: POST
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups
Content-Type: application/json

Example Request Body #

{
  "AllowCallService": true,
  "Id": 0,
  "Language": "EN",
  "Name": "3CX Test",
  "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7",
  "Props": {
    "LiveChatMaxCount": 20,
    "PersonalContactsMaxCount": 500,
    "PromptsMaxCount": 10,
    "SystemNumberFrom": "300",
    "SystemNumberTo": "319",
    "TrunkNumberFrom": "340",
    "TrunkNumberTo": "345",
    "UserNumberFrom": "320",
    "UserNumberTo": "339"
  },
  "TimeZoneId": "51",
  "DisableCustomPrompt": true
}

Example Response (201 Created) #

Includes a Location header containing the URL of the newly created department entity.

{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups/$entity",
  "Name": "3CX Test",
  "Id": 35,
  "Language": "EN",
  "Props": {
    "LiveChatMaxCount": 20,
    "PersonalContactsMaxCount": 500,
    "PromptsMaxCount": 10
  },
  "TimeZoneId": "51"
}

Error Response – Duplicate Name (400 Bad Request) #

{
  "error": {
    "message": "Name:nWARNINGS.XAPI.DUPLICATE",
    "details": [
      {
        "target": "Name",
        "message": "WARNINGS.XAPI.DUPLICATE"
      }
    ]
  }
}

Endpoint: Update Department Details #

Updates the properties or settings of an existing department.

HTTP Method: PATCH
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups({Department_Id})
Example URL: https://{{PBX_FQDN}}/xapi/v1/Groups(123)

Example Request Body #

{
  "Id": 123,
  "Name": "3CX Test Modif",
  "Props": {
    "LiveChatMaxCount": 25,
    "PersonalContactsMaxCount": 600
  }
}

Success Response: 204 No Content (no response body).

Endpoint: Delete a Department #

Permanently deletes a department from 3CX based on the given ID.

HTTP Method: POST
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups/Pbx.DeleteCompanyById

Request Body #

{
  "id": 123
}

Success Response: 204 No Content
Failure Response (404 Not Found): {"error": "Department not found"}

3. Users Management #

Endpoint: Get List of Users #

Retrieves data for all registered users, including their ID, name, extension number, email, and group/department membership.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Users

Query Parameters (Optional, for Pagination & Filtering) #

$top: Limits the number of users returned (Default: 100).
$skip: Skips a number of records for pagination (Default: 0).
$orderby: Sorts the data (Example: sorted by Number).
$select: Selects specific columns (Example: Id,FirstName,LastName,Number,EmailAddress).

4. System & Utilities #

Endpoint: Get Default Group Properties #

Retrieves the default properties of the group named “DEFAULT” to view the system’s base configuration and call routing.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq 'DEFAULT'

Example Response (200 OK) #

{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
  "value": [
    {
      "Name": "DEFAULT",
      "IsDefault": true,
      "HasMembers": true,
      "Number": "GRP0000",
      "Id": 95,
      "OfficeRoute": {
        "Route": { "Number": "101", "To": "Extension", "Name": "sysadmin" }
      },
      "OutOfOfficeRoute": {
        "Route": { "Number": "101", "To": "VoiceMail", "Name": "sysadmin" }
      }
    }
  ]
}

Endpoint: Get 3CX Version & Connection Test #

A utility endpoint for checking the API connection status while also identifying the 3CX system version currently running.

HTTP Method: GET (or a standard check method)
Main Response Header:

Look at the header when the response succeeds. It includes the property:

X-3CX-Version: 20.0.x.x (indicates the active 3CX version).

This documentation is adapted from 3CX’s official API specification guide.

5. Active Calls #

This endpoint is used to monitor calls that are currently active in real time.

Endpoint: Get Active Calls — Retrieves the list of all calls currently in progress on the 3CX system.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/ActiveCalls
Query Parameters (Optional):
- $top: Maximum number of records (default: 100)
- $skip: Pagination (default: 0)
- $orderby: Sort the data (example: EstablishedAt desc)
- $filter: Filter the data (example: Callee eq ‘101’)

Example Response (200 OK)

{
  "@odata.context": "https://{{PBX_FQDN}}/xapi/v1/$metadata#ActiveCalls",
  "value": [
    {
      "Id": "12345",
      "Caller": "+6281234567890",
      "Callee": "101",
      "EstablishedAt": "2026-07-07T07:45:12Z",
      "Duration": 125,
      "Direction": "Inbound",
      "Queue": null,
      "Status": "Connected"
    }
  ]
}

Note: this endpoint is very useful for real-time monitoring (call center dashboards, wallboards, etc.).

6. Reports & Call History #

XAPI provides several dedicated endpoints for retrieving reporting data and call history.

Endpoint: Call History View — Retrieves the full call history.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/CallHistoryView
Key Query Parameters:
- from & to (ISO format: 2026-07-01T00:00:00Z)
- $top, $skip, $orderby, $filter

Other Reporting Endpoints (examples):

/xapi/v1/ReportCallLogData/Pbx.GetCallLogData(…)
/xapi/v1/ReportAbandonedQueueCalls/Pbx.GetAbandonedQueueCallsData(…)
/xapi/v1/ReportQueuePerformanceOverview/…
/xapi/v1/ReportAgentLoginHistory/…

Example Usage (with a query):

GET https://{{PBX_FQDN}}/xapi/v1/CallHistoryView?$top=100&$skip=0&from=2026-07-01T00:00:00Z&to=2026-07-07T23:59:59Z

Tip: use Developer Tools (F12) in the 3CX Web Console while opening a report to see the exact query parameters used.

7. Trunks & Routing #

Endpoint: Get Trunks — Retrieves the list of registered SIP Trunks.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Trunks
Endpoint: Inbound/Outbound Rules

/xapi/v1/InboundRules
/xapi/v1/OutboundRules

Example Create/Update Trunk (POST/PATCH):

{
  "Name": "SIP Provider",
  "Host": "sip.provider.com",
  "Port": 5060,
  "Type": "SIP",
  ...
}

Note: routing management (DID, Caller ID rules) is usually done through the related Routes or DialPlans endpoints.

8. Phonebook & Contacts #

Endpoint: Global Phonebook

GET → https://{{PBX_FQDN}}/xapi/v1/Phonebook
POST → Add a new contact
PATCH → Update a contact
DELETE → Delete a contact

Example Request Body (Create Contact):

{
  "FirstName": "John",
  "LastName": "Doe",
  "Number": "+628123456789",
  "Email": "[email protected]",
  "Company": "PT ABC"
}

This endpoint is very useful for syncing contacts with a CRM.

9. System Settings & Utilities #

Endpoint: System Parameters — Retrieves and updates general system settings.

GET: https://{{PBX_FQDN}}/xapi/v1/SystemParameters
PATCH: Update specific parameters (e.g. recording settings, security, etc.).

Other Endpoints:

/xapi/v1/Defs → Get system definitions (enums, options)
/xapi/v1/Groups?$filter=Name eq ‘DEFAULT’ → Default Group Properties (already covered above)

10. Event Logs #

Endpoint: Get Event Logs — Retrieves system and event logs.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/EventLogs
Query Parameters: $top, $skip, $filter (by time, severity, etc.), $orderby=Timestamp desc

Example Response:

{
  "value": [
    {
      "Timestamp": "2026-07-07T07:50:00Z",
      "Severity": "Info",
      "Component": "CallManager",
      "Message": "Call established between 101 and +62812..."
    }
  ]
}

Additional Recommendations #

Swagger Reference — Access the full documentation directly from your PBX: https://{{PBX_FQDN}}/xapi/v1/swagger.yaml
Best Practices:
- Always use the System Owner role for maximum access.
- Implement refresh token logic, since tokens expire every hour.
- For large reports, use pagination ($top + $skip) to avoid timeouts.
- Use the F12 Network tab in the 3CX Web Console to “spy” on the endpoints and parameters the system uses.

IP Phone

3CX Softphone: Webclient and Apps

3CX Admin Console & Manajemen Sistem

Keamanan VoIP dan Troubleshoot

Developer

SIP TRUNK

WhatsApp Calling API

3CX REST API (XAPI) Endpoint Guide for Configuration

🔗 Base URL & Environment #

📑 Table of Contents #

1. Authentication / Authorization #

Endpoint: Get Token #

Request Body #

Example Response (200 OK) #

Error Response (401 Unauthorized) #

2. Departments Management #

Endpoint: Check if Department Exists #

Example Response – If Department Is Found (200 OK) #

Endpoint: Create a Department #

Example Request Body #

Example Response (201 Created) #

Error Response – Duplicate Name (400 Bad Request) #

Endpoint: Update Department Details #

Example Request Body #

Endpoint: Delete a Department #

Request Body #

3. Users Management #

Endpoint: Get List of Users #

Query Parameters (Optional, for Pagination & Filtering) #

4. System & Utilities #

Endpoint: Get Default Group Properties #

Example Response (200 OK) #

Endpoint: Get 3CX Version & Connection Test #

5. Active Calls #

6. Reports & Call History #

7. Trunks & Routing #

8. Phonebook & Contacts #

9. System Settings & Utilities #

10. Event Logs #

Additional Recommendations #