3CX API Documentation and examples

Download 3CX WebAPI Postman example (Save as and import file in postman)

GET methods

SET methods

Department management

Inbound / Outbound rules

System parameters

GET methods
SET methods
Department management
Queue management
Call control
Phonebook management
Extension management
Inbound / Outbound rules
System parameters

How it works

Creomate 3CX WebAPI is an HTTP/JSON module installed on your 3CX server. It is not the official 3CX API: it gives CRM, ERP and contact center systems simple HTTP access to calls, extensions, queues, the phonebook and routing rules.

Base URL: https://{{3CXFQDN}}/webapi/{{AccessKey}}/{method}
{{3CXFQDN}} is your 3CX address and port, {{AccessKey}} is your access key. The Postman collection uses the same variables. GET https://{{3CXFQDN}}/webapi/tcx returns the license information without a key.

Access keys: keys are listed in the AuthKeys.csv file of the module, one key per line: key;email;name;access. Access levels: get — read data, set — change settings, full — required for call control and extension management, system — system parameters. After you edit the file, reload it with csv.reread.

Example AuthKeys.csv:
key;email;name;access
XXXXXXXXXXXXXXXX;crm@example.com;CRM;full

Requests and responses: all responses are JSON. Methods that change data are also called with GET; parameter.set uses POST with a JSON body.

Quick links: Quick start · Webhook documentation · SQL API · FAQ · Changelog · Price · Buy

GET methods

Read data. Access key level: get

tcx — Get WebAPI license information

GET https://{{3CXFQDN}}/webapi/tcx

Returns the WebAPI module version and license details: expiry date, number of client licenses, concurrent calls and enabled modules. The same information is returned by https://{{3CXFQDN}}/webapi/{{AccessKey}}/.

{
    "product": "3CX REST API",
    "version": "3.0.8 20.1",
    "release": "Webhooks",
    "licenseExpire": "14.10.2033 21:32:17",
    "clientLicensesNum": "999",
    "concurrentCalls": 32,
    "sql": true,
    "api": true,
    "ai": true,
    "quality": false
}

license/activate — Activate WebAPI license

GET https://{{3CXFQDN}}/webapi/license/activate?key={license key}

Parameters:
• key — required — WebAPI license key

curl "https://pbx.example.com/webapi/license/activate?key=XXXX-XXXX-XXXX"

license/deactivate — Deactivate WebAPI license

GET https://{{3CXFQDN}}/webapi/license/deactivate?key={license key}

Parameters:
• key — required — WebAPI license key

curl "https://pbx.example.com/webapi/license/deactivate?key=XXXX-XXXX-XXXX"

pbx.calls.get — Get current number of calls

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/pbx.calls.get

Returns the number of active calls on the PBX.

{
    "result": 5
}

pbx.ac.get — Get active calls

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/pbx.ac.get

Returns active calls grouped by call ID, with every connection: extension, type, other party, direction, DID and status.

{
    "count": 2,
    "AConnByCallID": [
        {
            "callID": 46874,
            "direction": "Internal",
            "did": "",
            "AConnList": [
                {
                    "dnNum": "1739",
                    "dnType": "extension",
                    "externalParty": "1674",
                    "status": "Connected"
                },
                {
                    "dnNum": "1674",
                    "dnType": "extension",
                    "externalParty": "1739",
                    "status": "Connected"
                }
            ]
        },
        {
            "callID": 46883,
            "direction": "Internal",
            "did": "",
            "AConnList": [
                {
                    "dnNum": "1283",
                    "dnType": "extension",
                    "externalParty": "1126",
                    "status": "Connected"
                },
                {
                    "dnNum": "1126",
                    "dnType": "extension",
                    "externalParty": "1283",
                    "status": "Connected"
                }
            ]
        }
    ]
}

pbx.callsinfo.get — Get active calls with details

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/pbx.callsinfo.get

Like pbx.ac.get, plus call state, start and answer time, call owner, talkTo and routingTo.

{
    "count": 2,
    "callsInfo": [
        {
            "callID": 46874,
            "state": "Talking",
            "startedAt": "2022-12-29T08:37:16Z",
            "answeredAt": "2022-12-29T08:37:23Z",
            "did": "",
            "owner": {
                "dnNum": "1739",
                "dnType": "extension",
                "externalParty": "1674",
                "status": "Connected"
            },
            "talkTo": [
                {
                    "dnNum": "1674",
                    "dnType": "extension",
                    "externalParty": "1739",
                    "status": "Connected"
                }
            ],
            "routingTo": []
        },
        {
            "callID": 46864,
            "state": "Talking",
            "startedAt": "2022-12-29T08:23:58Z",
            "answeredAt": "2022-12-29T08:24:01Z",
            "did": "",
            "owner": {
                "dnNum": "1126",
                "dnType": "extension",
                "externalParty": "1283",
                "status": "Connected"
            },
            "talkTo": [
                {
                    "dnNum": "1283",
                    "dnType": "extension",
                    "externalParty": "1126",
                    "status": "Connected"
                }
            ],
            "routingTo": []
        }
    ]
}

all.line.get — Get external lines (SIP trunks)

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.line.get

Returns the numbers of all external lines.

{
    "nums": [
        "90000",
        "10002",
        "10000",
        "10001"
    ]
}

all.ext.get — Get all extensions (users)

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.ext.get

Returns the numbers of all user extensions.

{
    "nums": [
        "100",
        "101",
        "102",
        "103",
        "104",
        "105",
        "106",
        "520",
        "521",
        "522"
    ]
}

all.registered.get — Get registered extensions

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.registered.get

Returns extensions that have a registered device.

{
    "nums": [
        "100",
        "101",
        "102"
    ]
}

statuses.get — Get statuses of all extensions

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/statuses.get

Returns the forwarding status, status message and queue login status of every extension.

[
    {
        "num": "100",
        "fwdName": "Available",
        "fwdMessage": "Custom message1",
        "qGlobalStatus": true,
        "qStatus": [
            {
                "num": "801",
                "status": true
            },
            {
                "num": "805",
                "status": true
            }
        ]
    },
    {
        "num": "103",
        "fwdName": "Available",
        "fwdMessage": "",
        "qGlobalStatus": true,
        "qStatus": [
            {
                "num": "801",
                "status": false
            }
        ]
    },
    {
        "num": "106",
        "fwdName": "Available",
        "fwdMessage": "",
        "qGlobalStatus": true,
        "qStatus": []
    },
    {
        "num": "104",
        "fwdName": "Available",
        "fwdMessage": "",
        "qGlobalStatus": true,
        "qStatus": [
            {
                "num": "801",
                "status": false
            }
        ]
    }
]

all.group.get — Get ring groups

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.group.get

Returns the numbers of all ring groups.

{
    "nums": [
        "945",
        "803"
    ]
}

all.ivr.get — Get IVRs

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.ivr.get

Returns the numbers of all IVRs (digital receptionists).

{
    "nums": [
        "777",
        "QCB",
        "800",
        "804"
    ]
}

ext.info.get — Get extension properties

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.info.get?num=102

Returns extension settings: name, email, mobile, recording, voicemail, SIP credentials and departments.

Parameters:
• num — required — extension number

{
    "num": "102",
    "name": "John",
    "lastname": "Smith",
    "email": "j.smith@example.com",
    "mobile": "0601234567",
    "enabled": true,
    "externalCalls": true,
    "recordType": "External",
    "callerID": "",
    "deliverAudio": false,
    "sipID": "",
    "reinvite": true,
    "replaces": true,
    "vmemail": "Notification",
    "vmenabled": true,
    "vmpin": "0000",
    "vmplaycallerid": false,
    "vmplaydatetime": "None",
    "internal": false,
    "noAnswerTimeout": 0,
    "authID": "AUTH_ID",
    "authPassword": "********",
    "groups": [
        "__DEFAULT__",
       "Sales Dpt"
    ]
}

ext.state.get — Get extension status

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.state.get?num=102

Returns registration, call status, forwarding status and queue login status of one extension.

Parameters:
• num — required — extension number

{
    "num": "102",
    "registered": true,
    "status": "Free",
    "fwdName": "Available",
    "fwdMessage": "Custom message1",
    "qGlobalStatus": true,
    "qStatus": [
        {
            "num": "801",
            "status": true
        },
        {
            "num": "805",
            "status": true
        }
    ]
}

group.members.get — Get ring group members

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/group.members.get?num=803

Parameters:
• num — required — ring group number

{
    "count": 3,
    "members": [
        "520",
        "521",
        "522"
    ]
}

group.free.get — Get free ring group members

Access: get

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/group.free.get?num=803

Returns ring group members that are currently free.

Parameters:
• num — required — ring group number

{
    "count": 2,
    "members": [
        "520",
        "521"
    ]
}

SET methods

Change extension and ring group settings. Access key level: set

ext.fwd.set — Set extension forwarding status

Access: set

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.fwd.set?num=102&status=Available&message=Custom message

Parameters:
• num — required — extension number
• status — required — Available / Away / Out of office / Custom 1 / Custom 2
• message — optional — status message

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/ext.fwd.set?num=102&status=Away&message=Lunch"

{
    "result": true
}

ext.queueglobal.set — Log extension in/out of all queues

Access: set

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.queueglobal.set?num=102&log=on

Parameters:
• num — required — extension number
• log — required — on / off

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/ext.queueglobal.set?num=102&log=off"

{
    "result": true
}

ext.queue.set — Log extension in/out of a queue

Access: set

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.queue.set?num=102&queue=802&log=off

Parameters:
• num — required — extension number
• queue — required — queue number
• log — required — on / off

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/ext.queue.set?num=102&queue=802&log=on"

{
    "result": true
}

ext.options.set — Set extension options (legacy)

Access: set

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.options.set?num=102&enabled=on&external=on&recording=external

Parameters:
• num — required — extension number
• enabled — on / off — enable the extension
• external — on / off — allow external calls
• recording — off / external / all — call recording

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/ext.options.set?num=102&recording=all"

{
    "result": true
}

ext.rights — Set extension rights in a department

Access: set

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.rights?num=105&gname=GroupName1&rolename=users&showMyCalls=1&canBargeIn=0

Sets the role and individual rights of an extension in a department.

Parameters:
• num — required — extension number
• gname — required — department name
• rolename — role, e.g. users
• allowToManageCompanyBook, allowToChangePresence, canSeeGroupMembers, canSeeGroupCalls, showMyPresence, showMyPresenceOutside, showMyCalls, performOperations, canBargeIn, canIntercom, allowParking, allowIVR, assignClearOperations, canSeeGroupRecordings — 1 / 0 — individual rights

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/ext.rights?num=105&gname=Sales&rolename=users&canBargeIn=1"

group.members.set — Set ring group members

Access: set

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/group.members.set?num=945&members=101,103

Parameters:
• num — required — ring group number
• members — required — comma-separated extension numbers

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/group.members.set?num=945&members=101,103"

{
    "result": true
}

Department management

Departments (extension groups) and member roles

all.extgroup.get — Get departments

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.extgroup.get

Returns the names of all departments (extension groups).

{
    "extGroups": [
        "__DEFAULT__",
        "Company0",
        "Sales",
        "___FAVORITES___000"
    ]
}

extgroup.members.get — Get department members

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.members.get?name=__DEFAULT__

Parameters:
• name — required — department name

{
    "count": 3,
    "members": [
        "101",
        "102",
        "520"
    ]
}

extgroup.member.role — Get member role in a department

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.member.role?name=__DEFAULT__&num=100

Parameters:
• name — required — department name
• num — required — extension number

{
    "result": "system_owners"
}

extgroup.members.set — Add or remove department members

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.members.set?name=GroupName&nums=+102@0

Parameters:
• name — required — department name
• nums — required — comma-separated list of tasks, see the syntax below

Task syntax:
-* — remove all current members of the department (before the other tasks are applied)
+{extension}@{role ID} — add an extension with a role. Without @{role ID}, or with a non-existent ID, role 0 is used
-{extension} — remove an extension from the department
*@{role ID} — set the role for all current members (extensions added by the same request are not affected)

Role IDs: 0 — Users, 1 — Administrators, 2 — Group administrators, 3 — Managers, 4 — Group owners, 5 — System administrators, 6 — System owners

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/extgroup.members.set?name=Sales&nums=+102@0,+103@3,-104"

{
    "add": [
        "102"
    ],
    "remove": [],
    "change": []
}

extgroup.new — Create department

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.new?name={name}

Parameters:
• name — required — department name

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/extgroup.new?name=Sales"

{
    "result": true
}

extgroup.del — Delete department

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.del?name={name}

Parameters:
• name — required — department name

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/extgroup.del?name=Sales"

{
    "result": true
}

Queue management

Queues, agents and managers

queue.members.get — Get queue agents

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.members.get?num=802

Returns queue agents with their names and login status.

Parameters:
• num — required — queue number

{
    "count": 2,
    "members": [
        {
            "num": "102",
            "name": "Tom",
            "lastname": "Smith",
            "loggedIn": true
        },
        {
            "num": "104",
            "name": "Alex",
            "lastname": "Mulder",
            "loggedIn": false
        }
    ]
}

queue.managers.get — Get queue managers

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.managers.get?num=802

Parameters:
• num — required — queue number

{
    "nums": [
        "100",
        "103"
    ]
}

queue.free.get — Get free queue agents

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.free.get?num=804

Returns queue agents that are currently free.

Parameters:
• num — required — queue number

{
    "count": 1,
    "members": [
        {
            "num": "102",
            "name": "Tom",
            "lastname": "Smith",
            "loggedIn": true
        }
    ]
}

queue.talk.get — Get queue agents on a call

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.talk.get?num=802

Returns queue agents that are currently talking.

Parameters:
• num — required — queue number

{
    "count": 1,
    "members": [
        {
            "num": "102",
            "name": "Tom",
            "lastname": "Smith",
            "loggedIn": true
        }
    ]
}

queue.isfree.get — Check queue availability

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.isfree.get?num=802

Returns true if at least one agent in the queue is free.

Parameters:
• num — required — queue number

{
    "result": true
}

all.queue.get — Get queues

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.queue.get

Returns the numbers of all queues.

{
    "nums": [
        "820",
        "802",
        "804"
    ]
}

queue.size.get — Get queue length

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.size.get?num=801

Returns the number of calls waiting in the queue.

Parameters:
• num — required — queue number

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.size.get?num=801"

queue.agents.set — Set queue agents

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.agents.set?num=807&members=101,103

Replaces the agent list: all other agents are removed from the queue.

Parameters:
• num — required — queue number
• members — required — comma-separated extension numbers

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.agents.set?num=807&members=101,103"

{
    "result": true
}

queue.agents.add — Add queue agents

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.agents.add?num=807&members=101,103

Parameters:
• num — required — queue number
• members — required — comma-separated extension numbers

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.agents.add?num=807&members=104"

{
    "result": true
}

queue.agents.del — Remove queue agents

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.agents.del?num=807&members=101,103

Parameters:
• num — required — queue number
• members — required — comma-separated extension numbers

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.agents.del?num=807&members=104"

{
    "result": true
}

queue.skill.set — Set agent skill in a queue

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.skill.set?num=800&ext=911&skill=5

Used with skill-based polling strategies.

Parameters:
• num — required — queue number
• ext — required — extension number
• skill — required — skill level

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.skill.set?num=800&ext=911&skill=5"

queue.managers.set — Set queue managers

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.managers.set?num=807&managers=102,105

Replaces the manager list: all other managers are removed.

Parameters:
• num — required — queue number
• managers — required — comma-separated extension numbers

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.managers.set?num=807&managers=102,105"

{
    "result": true
}

queue.managers.add — Add queue managers

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.managers.add?num=807&managers=102,105

Parameters:
• num — required — queue number
• managers — required — comma-separated extension numbers

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.managers.add?num=807&managers=106"

{
    "result": true
}

queue.managers.del — Remove queue managers

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.managers.del?num=807&managers=102,105

Parameters:
• num — required — queue number
• managers — required — comma-separated extension numbers

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.managers.del?num=807&managers=106"

{
    "result": true
}

queue.new — Create queue

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.new?num=813&name=API Queue&pollingstrategy=3&mastertimeout=300&ringtimeout=30&enableintro=0&introfile=onhold.wav&announcequeueposition=0&announcementinterval=30&noanswerdest=extension&noanswerextension=101&primarygroup=__DEFAULT__

Parameters:
• num — required — queue number
• name — queue name
• pollingstrategy — polling strategy 0–13, see the list of strategies
• mastertimeout — maximum queue wait time, seconds
• ringtimeout — ring time, seconds
• enableintro — 0 / 1 — play intro
• introfile — intro file name, e.g. onhold.wav
• announcequeueposition — 0 / 1 — announce queue position
• announcementinterval — announcement interval, seconds
• noanswerdest — destination if no answer: extension / voicemail / ivr / queue / ringgroup / external / routepoint / none
• noanswerextension — internal number for the no-answer destination
• noanswerexternal — external number for the no-answer destination
• primarygroup — department, e.g. __DEFAULT__

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.new?num=813&name=Support&pollingstrategy=3"

{
    "result": "Create queue"
}

Polling strategy (0-13)

0 - Hunt
1 - Ring All
3 - Hunt random start (default)
4 - Next agent
5 - Longest waiting
6 - Least talk time
7 - Fewest answered
8 - Hunt by 3's
9 - First 3 available
10 - Skillbased routing Ring All
11 - Skillbased routing Hunt random start
12 - Skillbased routing Round robin
13 - Skillbased routing Fewest answered

queue.update — Update queue

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.update?num=813&name=API Queue&pollingstrategy=3&mastertimeout=300&ringtimeout=30&enableintro=0&introfile=onhold.wav&announcequeueposition=0&announcementinterval=30&noanswerdest=extension&noanswerextension=101&primarygroup=__DEFAULT__

Takes the same parameters as queue.new.

Parameters:
• num — required — queue number
• name — queue name
• pollingstrategy — polling strategy 0–13, see the list of strategies
• mastertimeout — maximum queue wait time, seconds
• ringtimeout — ring time, seconds
• enableintro — 0 / 1 — play intro
• introfile — intro file name, e.g. onhold.wav
• announcequeueposition — 0 / 1 — announce queue position
• announcementinterval — announcement interval, seconds
• noanswerdest — destination if no answer: extension / voicemail / ivr / queue / ringgroup / external / routepoint / none
• noanswerextension — internal number for the no-answer destination
• noanswerexternal — external number for the no-answer destination
• primarygroup — department, e.g. __DEFAULT__

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.update?num=813&ringtimeout=20"

{
    "result": "Update queue"
}

queue.del — Delete queue

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.del?num=813

Parameters:
• num — required — queue number

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/queue.del?num=813"

{
    "result": "Delete queue"
}

Call control

Click-to-call, answer, transfer, drop, barge-in and recording. Access key level: full

makecall — Make a call from an extension (click-to-call)

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/makecall?first=102&second=381629759787&contact=102&timeout=2000

The PBX first calls the extension (first leg), then the number (second leg). Returns chid. Track the call by chid in webhook events.

Parameters:
• first — required — extension number, first leg
• second — required — number to call, second leg
• contact — optional — device contact, see ext.devices.get
• timeout — request timeout, ms (at least 2000)

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/makecall?first=102&second=381629759787&timeout=2000"

{
    "chid": "00000000-01dc-226c-d961-c78c00000001"
}

makecall — Make a call via IVR, queue or CFD app

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/makecall?first=801&second=381629759787&timeout=2000

The first leg is an IVR, queue or Call Flow Designer app, the second leg is the number to call. Returns chid. Track the call by chid in webhook events.

Parameters:
• first — required — IVR, queue or CFD app number
• second — required — number to call
• timeout — request timeout, ms (at least 2000)

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/makecall?first=801&second=381629759787&timeout=2000"

{
    "chid": "00000000-01dc-226c-d961-c78c00000002"
}

ext.devices.get — Get extension devices

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.devices.get?num=102

Returns the registered devices of an extension. Use the contact value in call control methods to choose a device.

Parameters:
• num — required — extension number

{
    "count": 2,
    "devices": [
        {
            "userAgent": "3CX Mobile Client",
            "contact": "sip:102@127.0.0.1:5483;rinstance=5a6cb7ecb40359bf"
        },
        {
            "userAgent": "3CX WebRTC proxy",
            "contact": "sip:102@127.0.0.1:5063;rinstance=b206569d67c8dd02"
        }
    ]
}

drop — Drop an active call

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/drop?num=102&contact=102&external=787

Parameters:
• num — required — extension number
• contact — optional — device contact
• external — optional — external number

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/drop?num=102"

{
    "result": "Drop"
}

answer — Answer a call

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/answer?num=102&contact=102

Parameters:
• num — required — extension number
• contact — device contact

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/answer?num=102&contact=102"

{
    "result": "Answer"
}

transfer — Blind transfer (cold, unattended)

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/transfer?num=102&contact=102&dest=101

Parameters:
• num — required — extension number
• contact — device contact
• dest — required — transfer destination number

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/transfer?num=102&dest=101"

{
    "result": "Transfer"
}

join — Join calls

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/join?num=102

Parameters:
• num — required — extension number

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/join?num=102"

{
    "result": "Join"
}

bargein — Barge in, listen or whisper

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/bargein?internal=100&num=101&mode=bargein

Parameters:
• internal — internal leg of the call
• external — external leg of the call (optional)
• num — required — extension number
• contact — optional — device contact
• mode — bargein / listen / whisper

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/bargein?internal=100&num=101&mode=listen"

{
    "result": "Barge in"
}

recording.change — Start, stop, pause or resume call recording

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/recording.change?num=100&action=stop&contact=100

Parameters:
• num — required — extension number
• action — required — start / stop / pause / resume
• contact — device contact

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/recording.change?num=100&action=pause&contact=100"

Phonebook management

Access key level: set or full

contact.find — Find a contact in the phonebook

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/contact.find?num=997&min_len=3

Searches by exact match or by the end of the number, with a minimum match length. Returns contact IDs.

Parameters:
• num — required — phone number
• min_len — minimum match length

{
    "id": [
        6,
        7
    ]
}

contact.new — Create a contact

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/contact.new?firstname=FirstName&lastname=LastName&company=Company&phone=Mobile&data0=Mobile2&data1=Home&data2=Home2&data3=Business&data4=Business2&data5=Email&data6=Other&data7=Businessfax&data8=Homefax&data9=Pager

Returns the ID of the new contact.

Parameters:
• firstname — first name
• lastname — last name
• company — company
• phone, data0–data9 — phone — Mobile, data0 — Mobile 2, data1 — Home, data2 — Home 2, data3 — Business, data4 — Business 2, data5 — Email, data6 — Other, data7 — Business fax, data8 — Home fax, data9 — Pager

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/contact.new?firstname=John&lastname=Smith&company=Acme&phone=381601234567"

{
    "id": 5
}

contact.del — Delete a contact

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/contact.del?id=5

Parameters:
• id — required — contact ID

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/contact.del?id=5"

{
    "result": "Delete contact"
}

contact.update — Update a contact

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/contact.update?id=4&firstname=FirstName&lastname=LastName&company=Company&phone=Mobile&data0=Mobile2&data1=Home&data2=Home2&data3=Business&data4=Business2&data5=Email&data6=Other&data7=Businessfax&data8=Homefax&data9=Pager

Parameters:
• id — required — contact ID
• firstname — first name
• lastname — last name
• company — company
• phone, data0–data9 — phone — Mobile, data0 — Mobile 2, data1 — Home, data2 — Home 2, data3 — Business, data4 — Business 2, data5 — Email, data6 — Other, data7 — Business fax, data8 — Home fax, data9 — Pager

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/contact.update?id=4&company=Acme"

{
    "result": "Update contact"
}

contact.get — Get a contact

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/contact.get?id=4

Parameters:
• id — required — contact ID

{
    "name": "FirstName",
    "lastName": "LastName",
    "company": "Company",
    "crmContactData": "",
    "tag": "",
    "phone": "Mobile",
    "data0": "Mobile2",
    "data1": "Home",
    "data2": "Home2",
    "data3": "Business",
    "data4": "Business2",
    "data5": "Email",
    "data6": "Other",
    "data7": "Businessfax",
    "data8": "Homefax",
    "data9": "Pager"
}

Extension management

Access key level: full

ext.new — Create extension

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.new?num=100

Creates an extension. Set its properties with ext.update.

Parameters:
• num — required — extension number

Note: when an extension is created via WebAPI, the password complexity is not checked.

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/ext.new?num=300"

{
    "result": "Create extension"
}

ext.del — Delete extension

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.del?num=100

Parameters:
• num — required — extension number

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/ext.del?num=300"

{
    "result": "Delete extension"
}

ext.update — Update extension

Access: full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.update?num=300&callerid=381629759787

Pass only the parameters you want to change.

Parameters:
• num — required — extension number
• enabled — 0 / 1
• firstname, lastname, email, mobile — user details
• authid, authpass — SIP authentication ID and password
• callerid — outbound caller ID
• deliveraudio — 0 / 1
• recordcalls — 0 / 1 / 2
• sipid — SIP ID
• reinvite — 0 / 1
• replaces — 0 / 1
• vmemail — 0 / 1 / 2 / 3
• vmenabled — 0 / 1 — voicemail
• vmpin — voicemail PIN
• vmplaycallerid — 0 / 1
• vmplaydatetime — 0 / 1 / 2
• internal — 0 / 1
• noanswertimeout — no answer timeout, seconds

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/ext.update?num=300&firstname=John&lastname=Smith&email=john@example.com"

{
    "result": "Update extension"
}

Inbound / Outbound rules

Outbound rules, inbound rules and DID numbers. Access key level: set or full

outboundrules.get — Get all outbound rules

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrules.get

{
    "count": 6,
    "minPriority": 1,
    "maxPriority": 6,
    "rules": [
        {
            "priority": 1,
            "name": "99 creomate.3cx.eu"
        },
        {
            "priority": 2,
            "name": "CZ"
        },
        {
            "priority": 3,
            "name": "Serbia"
        },
        {
            "priority": 4,
            "name": "North Macedonia 381"
        },
        {
            "priority": 5,
            "name": "USA/Canada"
        }
        {
            "priority": 6,
            "name": "UK"
        }
    ]
}

outboundrule.get — Get an outbound rule

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.get?rulename=UK&rulepriority=13

Specify rulename or rulepriority.

Parameters:
• rulename — rule name
• rulepriority — rule priority

{
    "name": "UK",
    "priority": 13,
    "prefix": "44",
    "numberLength": "9,10,11",
    "groups": [
        "__DEFAULT__"
    ],
    "ranges": [
        "101",
        "102"
    ],
    "numberOfRoutes": 5,
    "routes": [
        "Zadarma OUT +381 21 322 0030.0..",
        ".0..",
        ".0..",
        ".0..",
        ".0.."
    ]
}

outboundrule.new — Create an outbound rule

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.new?name=CZ&priority=13

Parameters:
• name — required — rule name
• priority — rule priority

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/outboundrule.new?name=CZ&priority=13"

{
    "result": "Created outbound rule."
}

outboundrule.set — Change an outbound rule

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.set?rulename=UK&rulepriority=13&name=UK1&priority=12&prefix=420&numberlength=12&groups=__DEFAULT__&groupsadd=Sales&groupsdel=Sales&ranges=101,102&rangesadd=101,102&routes=Zadarma OUT.1.3.caller,.0..,.0..,.0..,.0..

Parameters:
• rulename / rulepriority — rule to change
• name, priority — new name and priority
• prefix — calls to numbers starting with
• numberlength — number length(s)
• groups / groupsadd / groupsdel — departments: replace / add / remove
• ranges / rangesadd — extension ranges: replace / add
• routes — routes, comma-separated

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/outboundrule.set?rulename=UK&prefix=44"

{
    "result": "Changed outbound rule."
}

outboundrule.before — Move an outbound rule up

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.before?rulename=Name&rulepriority=11&beforename=Name&beforepriority=5

Moves the rule before another rule.

Parameters:
• rulename / rulepriority — rule to move
• beforename / beforepriority — rule to place it before

{
    "result": "Outbound rule moved."
}

outboundrule.after — Move an outbound rule down

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.after?rulename=Name1&rulepriority=3&aftername=Name2&afterpriority=4

Moves the rule after another rule.

Parameters:
• rulename / rulepriority — rule to move
• aftername / afterpriority — rule to place it after

{
    "result": "Outbound rule moved."
}

outboundrule.del — Delete an outbound rule

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.del?name=CZ&priority=13

Parameters:
• name — rule name
• priority — rule priority

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/outboundrule.del?name=CZ"

{
    "result": "Deleted outbound rule."
}

inboundrules.get — Get inbound rules (assigned DIDs) of a trunk

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/inboundrules.get?linename=SoftNet_381213220030

Parameters:
• linename — required — SIP trunk name

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/inboundrules.get?linename=SoftNet_381213220030"

inboundrule.get — Get an inbound rule

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/inboundrule.get?linename=SoftNet_381213220030&did=3810042213220030

Parameters:
• linename — required — SIP trunk name
• did — required — DID number

{
    "type": "IVR",
    "internal": "809",
    "external": "",
    "name": "DID-3810042213220030"
}

inboundrule.add — Add an inbound rule

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/inboundrule.add?linename=SoftNet_381213220030&did=381213220032&type=extension&internal=100&external=&name=DID-friendly-name

Parameters:
• linename — required — SIP trunk name
• did — required — DID number
• type — destination type, e.g. Extension, IVR
• internal — internal destination number
• external — external destination number
• name — rule name

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/inboundrule.add?linename=SoftNet_381213220030&did=381213220032&type=extension&internal=100&name=Support"

inboundrule.set — Change an inbound rule

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/inboundrule.set?linename=SoftNet_381213220030&did=3810042213220031&type=Extension&internal=100&external=&name=DID-friendly-name

Replaces the destination of the inbound rule.

Parameters:
• linename — required — SIP trunk name
• did — required — DID number
• type — destination type, e.g. Extension, IVR
• internal — internal destination number
• external — external destination number
• name — rule name

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/inboundrule.set?linename=SoftNet_381213220030&did=381213220031&type=Extension&internal=100&name=Sales"

{
    "result": "Changed inbound rule."
}

inboundrule.del — Delete an inbound rule

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/inboundrule.del?linename=SoftNet_381213220030&did=381213220030

Parameters:
• linename — required — SIP trunk name
• did — required — DID number

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/inboundrule.del?linename=SoftNet_381213220030&did=381213220030"

dids.get — Get DID numbers of a trunk

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/dids.get?linename=SoftNet_381213220030

Parameters:
• linename — required — SIP trunk name

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/dids.get?linename=SoftNet_381213220030"

did.add — Add a DID number to a trunk

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/did.add?linename=SoftNet_381213220030&did=381213220032

Parameters:
• linename — required — SIP trunk name
• did — required — DID number

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/did.add?linename=SoftNet_381213220030&did=381213220032"

dids.set — Set DID numbers of a trunk

Access: set or full

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/dids.set?linename=SoftNet_381213220030&dids=381213220030,381213220031

Replaces the DID list of the trunk.

Parameters:
• linename — required — SIP trunk name
• dids — required — comma-separated DID numbers

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/dids.set?linename=SoftNet_381213220030&dids=381213220030,381213220031"

System parameters

Access key level: system

csv.reread — Reload CSV files

Access: system

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/csv.reread

Reloads the WebAPI CSV files, for example AuthKeys.csv after you change access keys.

{
"result":"Success"
}

cfd.reset — Reload Call Flow Designer apps

Access: system

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/cfd.reset?names=900,901

Parameters:
• names — required — CFD app numbers or names, comma-separated

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/cfd.reset?names=900"

{
"result":"CFD scripts have been reset"
}

parameter.get — Get a system parameter

Access: system

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/parameter.get?name={parameter name}

Parameters:
• name — required — parameter name

{
    "name": "VERSION",
    "description": "Version",
    "value": "20.0.5.384",
    "type": 0
}

parameter.set — Set a system parameter

Access: system

POST https://{{3CXFQDN}}/webapi/{{AccessKey}}/parameter.set

Send a POST request with a JSON body: name, description, value, type.

Body: {"name": "PARAMETER_NAME", "description": "Description", "value": "1", "type": 0}

{
    "result": true
}

parameters.del — Delete system parameters

Access: system

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/parameters.del?name={parameter1,parameter2}

Parameters:
• name — required — parameter names, comma-separated

Example: curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/parameters.del?name=PARAM1,PARAM2"

{
    "result": "The parameter list has been removed"
}

dn.prop.get — Get extension (DN) properties

Access: system

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/dn.prop.get?num=300

Parameters:
• num — required — extension or other DN number

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/dn.prop.get?num=300"

dn.prop.set — Set an extension (DN) property

Access: system

GET https://{{3CXFQDN}}/webapi/{{AccessKey}}/dn.prop.set?num=300&name=PUSH_EXTENSION&value=1

Parameters:
• num — required — extension or other DN number
• name — required — property name
• value — required — property value

curl "https://pbx.example.com/webapi/YOUR_ACCESS_KEY/dn.prop.set?num=300&name=PUSH_EXTENSION&value=1"

Try 3CX WebAPI

Integrate 3CX with your CRM, ERP or contact center. Start with the quick start guide or write to support@creomate.com.

See prices Buy now

Pay attention. When creating an extension using WebAPI, the password complexity is not checked