3CX Configuration API

What is the Configuration API?

The 3CX Configuration API (XAPI), introduced in 3CX Version 20, offers a REST-based interface that enables programmatic control over nearly every configuration aspect within the 3CX phone system, replicating capabilities typically accessed via the admin console. Built on OData standards and OpenAPI specifications, this API allows developers to integrate, automate, and customize the 3CX environment efficiently.

Key Features of the Configuration API

  • Comprehensive Management: With endpoints for managing departments, users, call routing, system extensions, and other configurations, the API enables users to perform nearly all administrative actions programmatically. From checking if a department exists to configure shared parking spaces, almost every element of 3CX can be managed through code.
  • Automation: The API allows automation of common administrative tasks, such as creating departments, assigning user roles, and managing extensions. This reduces the need for manual intervention in the admin console, saving time and minimizing the chance of errors.
  • Integration: The API facilitates seamless integration of the 3CX phone system with other business applications. You can use it to synchronize user data, manage departments, and configure call routing to ensure smooth interoperability between 3CX and external services. Integrating 3CX into broader workflows enhances communication and productivity without requiring manual synchronization.
  • Scalability: Designed with scalability in mind, the API enables efficient management of configurations as organizations grow, allowing for easy expansion of users, departments, and other entities without overwhelming administrative overhead.

Configuring the API Integration

Go to Admin Console > Integrations > API:

  1. Press the Add button to create a new client application.
  2. Specify the Client ID (DN for accessing the route point, which is also needed for authorization).
  3. If using the Configuration scope, check the 3CX Configuration API Access checkbox for this application.
  4. Specify Department and Role for Service Principal, for appropriate API access level.
  5. After successfully creating a new API instance, you will receive an API key for your third-party applications. This key will be shown only once, so be sure to save it for future use.

That's it! You've successfully completed the PBX configuration.

Please note: You must have an 8SC and higher AI license to use the 3CX Configuration API.

How it Works

RESTful API

The 3CX Configuration API is a RESTful Web API built on the OData protocol, offering secure and versatile endpoints to manage and configure nearly every aspect of the 3CX system. This API mirrors the functionality available in the 3CX admin console, enabling programmatic control over user management, department setup, call routing, system extensions, and more. All endpoints are designed to be safe and reliable, ensuring that they do not interfere with core PBX functions or compromise system stability.

For more details, refer to the 3CX Configuration API Endpoint Specification.

Authentication Tokens

The Configuration API supports two types of tokens for secure access:

  • Multi-Company Admin Tokens: Enable full access to manage all departments and entities across the 3CX system, suitable for administrators in multi-company environments.
  • User Tokens: Grant access limited to the user’s assigned roles and departmental permissions, providing controlled access to specific configuration tasks.

JSON and OpenAPI

With its OpenAPI specification, the 3CX Configuration API is compatible with various development tools, including Postman, for straightforward integration. The API accepts JSON-formatted requests and responses, making it easy for developers to work with and automate configuration tasks.

Authentication Process

The 3CX Configuration API supports secure access through two types of authentication tokens: Multi-Company Admin Tokens and User Tokens. Each type of token provides different access levels, allowing for flexibility in managing permissions across various roles and departments within the 3CX environment.

Tokens

  • Please specify the Department and Role in your Service Principal Settings. Setting a role as "System Owner" or "System Admin" will grant system-wide rights. Other roles will have corresponding rights.
  • How to Obtain:
  • Call the /connect/token endpoint with a POST request with MIME type application/x-www-form-urlencoded.

The request body should contain:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

Upon successful authentication, an access token will be returned in the response, which can then be used for subsequent API requests.

  • Token Validity: The token is valid for 60 minutes, after which it will need to be refreshed or re-obtained.

Using Access Tokens

Once an access token is obtained, include it in the Authorization header of your API requests as a Bearer token:

Authorization: Bearer ACCESS_TOKEN

Quick Test - Validating Token Authentication

To quickly verify that your token is valid and the API connection is properly established, use the "Quick Test" endpoint:

  • Endpoint: GET /xapi/v1/Defs?$select=Id
  • Response: A 200 OK response confirms valid authentication, and the headers will contain the 3CX system version.

Important Notes

  • Token Expiry: All access tokens expire after one hour. Applications must handle token expiration by either re-authenticating or refreshing the token in order to maintain a continuous connection.
  • Security: Always handle tokens securely and avoid exposing them in client-side code or unsecured storage locations.

XAPI Application Example

For detailed steps on setting up an XAPI application with the PBX Configuration API, please refer to the XAPI Tutorial Github repository the example covers basic functionality and API calls demonstrating.

See also

Last updated

This document was last updated 10 September 2026

https://www.3cx.com/docs/configuration-rest-api/