---
title: 3CX REST API (XAPI) Endpoint Guide for Configuration
description: "This document provides a complete guide to the [REST API](https://en.wikipedia.org/wiki/Representational_state_transfer) 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…"
url: "https://solusipbx.id/en/pusat-bantuan/3cx-rest-api-endpoint-specification/"
updated: "2026-10-02"
category: Developer
---

# 3CX REST API (XAPI) Endpoint Guide for Configuration

This document provides a complete guide to the [REST API](https://en.wikipedia.org/wiki/Representational_state_transfer) 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

1. Authentication / Authorization
2. Departments Management
3. Users Management
4. System & Utilities
5. Active Calls
6. Reports & Call History
7. Trunk & Routing
8. Phonebook & Contacts
9. System Settings & Utility
10. 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": "john@example.com",
  "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

1. **Swagger Reference** — Access the full documentation directly from your PBX: https://{{PBX_FQDN}}/xapi/v1/swagger.yaml
2. **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.