3CX API Documentation and examples
Download 3CX WebAPI Postman example (Save as and import file in postman)
3CX Call-Control (Click-to-call)
GET Methods
Get key required
Get 3CX WebAPI license information
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ or https://{{3CXFQDN}}/webapi/tcx/
{
"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
}Get 3CX phone current number of calls
https://{{3CXFQDN}}/webapi/{{AccessKey}}/pbx.calls.get
{
"result": 5
}Get 3CX phone current calls
https://{{3CXFQDN}}/webapi/{{AccessKey}}/pbx.ac.get
{
"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"
}
]
}
]
}Get 3CX phone current calls with an additional information
https://{{3CXFQDN}}/webapi/{{AccessKey}}/pbx.callsinfo.get
{
"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": []
}
]
}Get 3CX external lines information (SIP trunks)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.line.get
{
"nums": [
"90000",
"10002",
"10000",
"10001"
]
}Get 3CX all extensions (users)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.ext.get
{
"nums": [
"100",
"101",
"102",
"103",
"104",
"105",
"106",
"520",
"521",
"522"
]
}Get 3CX all registered extensions
https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.registered.get
{
"nums": [
"100",
"101",
"102"
]
}Get 3CX statuses of all extensions
https://{{3CXFQDN}}/webapi/{{AccessKey}}/statuses.get
[
{
"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
}
]
}
]Get 3CX list of ring groups
https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.group.get
{
"nums": [
"945",
"803"
]
}Get 3CX list of IVR's (Get | Set | Full)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.ivr.get
{
"nums": [
"777",
"QCB",
"800",
"804"
]
}Get 3CX extension properties
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.info.get?num=102
{
"num": "102",
"name": "John",
"lastname": "Smith",
"email": "j.smith@creomate.com",
"mobile": "0629759787",
"enabled": true,
"externalCalls": true,
"recordType": "External",
"callerID": "",
"deliverAudio": false,
"sipID": "",
"reinvite": true,
"replaces": true,
"vmemail": "Notification",
"vmenabled": true,
"vmpin": "165679",
"vmplaycallerid": false,
"vmplaydatetime": "None",
"internal": false,
"noAnswerTimeout": 0
}Get 3CX extension status
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.state.get?num=102
{
"num": "100",
"registered": true,
"status": "Free",
"fwdName": "Available",
"fwdMessage": "Custom message1",
"qGlobalStatus": true,
"qStatus": [
{
"num": "801",
"status": true
},
{
"num": "805",
"status": true
}
]
}Get 3CX ring group members
https://{{3CXFQDN}}/webapi/{{AccessKey}}/group.members.get?num=803
{
"count": 3,
"members": [
"520",
"521",
"522"
]
}Get 3CX free ring group members
https://{{3CXFQDN}}/webapi/{{AccessKey}}/group.free.get?num=803
{
"count": 2,
"members": [
"520",
"521"
]
}SET Methods
Set key required
Set 3CX extension forwarding status
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.fwd.set?num=102&status&message=Custom message
{
"result": true
}Set 3CX extension global queue status
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.queueglobal.set?num=102&log=on
{
"result": true
}Set 3CX extension queue status
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.queue.set?num=102&queue=802&log=off
{
"result": true
}Set 3CX extension recording options (legacy)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.options.set?num=102&enabled=on&external=on&recording=external
{
"result": true
}Set 3CX ring group members
https://{{3CXFQDN}}/webapi/{{AccessKey}}/group.members.set?num=945&members=101,103
{
"result": true
}3CX Department management
Get 3CX list of extension group (departments)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.extgroup.get
{
"extGroups": [
"__DEFAULT__",
"Company0",
"Sales",
"___FAVORITES___000"
]
}Get 3CX group (department) members
https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.members.get?name=__DEFAULT__
{
"count": 3,
"members": [
"101",
"102",
"520"
]
}3CX Get department member role
https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.member.role?name=__DEFAULT__&num=100
{
"result": "system_owners"
}3CX Add members to the department
https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.members.set?name=GroupName&nums=+102@0
-* – delete all members of the group that were included in it before executing this command
+{extension}@{role ID} – include an extension with the role (set of rights) ID in the group. If you use @{role ID} or use a non-existent ID, the role with ID 0 will be used.
-{extension} – exclude the extension from the group
{added}@{Role ID} – a joint group is called a role (rights setter).
*@{Role ID} – all group members have a role ID (rights). By "all members of the group" we mean the extensions that were included in it before the execution of this command. That is, this task does not apply to the extensions that are specified in the addition command.
List of roles (ID – role name):
0 – Users
1 – Administrators
2 – Group administrators
3 – Managers
4 – Group owners
5 – System administrators
6 – System owners
-* – delete all members of the group that were included in it before executing this command
+{extension}@{role ID} – include an extension with the role (set of rights) ID in the group. If you use @{role ID} or use a non-existent ID, the role with ID 0 will be used.
-{extension} – exclude the extension from the group
{added}@{Role ID} – a joint group is called a role (rights setter).
*@{Role ID} – all group members have a role ID (rights). By "all members of the group" we mean the extensions that were included in it before the execution of this command. That is, this task does not apply to the extensions that are specified in the addition command.
List of roles (ID – role name):
0 – Users
1 – Administrators
2 – Group administrators
3 – Managers
4 – Group owners
5 – System administrators
6 – System owners
{
"add": [
"102"
],
"remove": [],
"change": []
}3CX Create extension group (department)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.new?name={name}
{
"result": true
}3CX Delete extension group (department)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/extgroup.del?name={name}
{
"result": true
}3CX queue management
Get 3CX queue members
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.members.get?num=802
{
"count": 2,
"members": [
{
"num": "102",
"name": "Tom",
"lastname": "Smith",
"loggedIn": true
},
{
"num": "104",
"name": "Alex",
"lastname": "Mulder",
"loggedIn": false
}
]
}Get 3CX queue managers
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.managers.get?num=802
{
"nums": [
"100",
"103"
]
}Get 3CX free queue members
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.free.get?num=804
{
"count": 1,
"members": [
{
"num": "102",
"name": "Tom",
"lastname": "Smith",
"loggedIn": true
}
]
}Get 3CX talking queue members
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.talk.get?num=802
{
"count": 1,
"members": [
{
"num": "102",
"name": "Tom",
"lastname": "Smith",
"loggedIn": true
}
]
}Get 3CX queue availability (is there at least one free member in the queue?)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.isfree.get?num=802
{
"result": true
}Get 3CX list of queues
https://{{3CXFQDN}}/webapi/{{AccessKey}}/all.queue.get
{
"nums": [
"820",
"802",
"804"
]
}Set 3CX queue agents (operators). All others will be deleted.
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.agents.set?num=807&members=101,103
{
"result": true
}Add 3CX queue agents (operators)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.agents.add?num=807&members=101,103
{
"result": true
}Delete 3CX queue agents (operators)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.agents.del?num=807&members=101,103
{
"result": true
}Set 3CX queue managers. All others will be deleted.
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.managers.set?num=807&managers=102,105
{
"result": true
}Add 3CX queue managers
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.managers.add?num=807&managers=102,105
{
"result": true
}Delete 3CX queue managers
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.managers.del?num=807&managers=102,105
{
"result": true
}Create 3CX queue
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
{
"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
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
Update 3CX queue
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
{
"result": "Update queue"
}Delete 3CX queue
https://{{3CXFQDN}}/webapi/{{AccessKey}}/queue.del?num=813
{
"result": "Delete queue"
}3CX Call control API Methods
Full key required
3CX make call
https://{{3CXFQDN}}/webapi/{{AccessKey}}/makecall?first=102&second=420774852529&contact=102
NB: For automatic calling, you can use the IVR, queue or CFD number as the first parameter
NB: For automatic calling, you can use the IVR, queue or CFD number as the first parameter
{
"first": "102",
"second": "420774852529"
}3CX get user's registered devices for contact value
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.devices.get?num=102
{
"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"
}
]
}3CX drop active call
https://{{3CXFQDN}}/webapi/{{AccessKey}}/drop?num=102&contact=102&external=787
Num - Extension (mandatory), Contact - Device contact (optional), External - External number (optional)
Num - Extension (mandatory), Contact - Device contact (optional), External - External number (optional)
{
"result": "Drop"
}3CX answer call
https://{{3CXFQDN}}/webapi/{{AccessKey}}/answer?num=102&contact=102
{
"result": "Answer"
}3CX blind transfer call (cold, unattended)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/transfer?num=102&contact=102&dest=101
{
"result": "Transfer"
}3CX join call
https://{{3CXFQDN}}/webapi/{{AccessKey}}/join?num=102
{
"result": "Join"
}3CX barge in active call
https://{{3CXFQDN}}/webapi/{{AccessKey}}/bargein?internal={internal leg}&external={external leg}&num={internal number}
{
"result": "Barge in"
}3CX phonebook management
Set or Full key required
3CX search for a contact in the phone book
https://{{3CXFQDN}}/webapi/{{AccessKey}}/contact.find?num=997&min_len=3
search the phonebook with the minimum length exact match or ends with the number
search the phonebook with the minimum length exact match or ends with the number
{
"id": [
6,
7
]
}3CX Create a contact in phonebook
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
{
"id": 5
}3CX delete contact from phonebook
https://{{3CXFQDN}}/webapi/{{AccessKey}}/contact.del?id=5
{
"result": "Delete contact"
}3CX update contact in phonebook
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
{
"result": "Update contact"
}3CX get contact information from phonebook
https://{{3CXFQDN}}/webapi/{{AccessKey}}/contact.get?id=4
{
"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"
}3CX Extension management
Full key required
3CX create extension
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.new?num=100
{
"result": "Create extension"
}3CX delete extension
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.del?num=100
{
"result": "Delete extension"
}3CX update extension
https://{{3CXFQDN}}/webapi/{{AccessKey}}/ext.update?num=300&enabled={0/1}&firstname=Firstname&lastname=Lastname&email=api@api.com&mobile={}&authid=300&authpass=300&callerid={}&deliveraudio={0/1}&recordcalls={0/1/2}&sipid={}&reinvite={0/1}&replaces={0/1}&vmemail={0/1/2/3}&vmenabled={0/1}&vmpin={}&vmplaycallerid={0/1}&vmplaydatetime={0/1/2}&internal={0/1}&noanswertimeout={}
{
"result": "Update extension"
}3CX Inbound / Outbound rules management
Set or Full key required
3CX get all outbound rules list
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"
}
]
}3CX get outbound rule
https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.get?rulename=UK&rulepriority=13
Specify rulename OR rulepriority
Specify rulename OR rulepriority
{
"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.."
]
}3CX Set outbound rule with replace
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..
{
"result": "Changed outbound rule."
}3CX Create outbound rule
https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.new?name=CZ&priority=13
{
"result": "Created outbound rule."
}3CX Delete outbound rule
https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.del?name=CZ&priority=13
{
"result": "Deleted outbound rule."
}3CX get inbound rule
https://{{3CXFQDN}}/webapi/{{AccessKey}}/inboundrule.get?linename=SoftNet_381213220030&did=3810042213220030
{
"type": "IVR",
"internal": "809",
"external": "",
"name": "DID-3810042213220030"
}3CX set inbound rule (with replace)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/inboundrule.set?linename=SoftNet_381213220030&did=3810042213220031&type=Extension&internal=100&external=&name=DID-friendly-name
{
"result": "Changed inbound rule."
}3CX outbound rule move down
https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.after?rulename=Name1&rulepriority=3&aftername=Name2&afterpriority=4
{
"result": "Outbound rule moved."
}3CX outbound rule move up
https://{{3CXFQDN}}/webapi/{{AccessKey}}/outboundrule.before?rulename=Name&rulepriority=11&beforename=Name&beforepriority=5
{
"result": "Outbound rule moved."
}3CX Server management
System key required
Read CSV files WebAPI
https://{{3CXFQDN}}/webapi/{{AccessKey}}/csv.reread
{
"result":"Success"
}Reload 3CX CFD applications
https://{{3CXFQDN}}/webapi/{{AccessKey}}/cfd.reset?names=900,901 or script1,script2, ... ,scriptN
{
"result":"CFD scripts have been reset"
}Get 3CX system parameter
https://{{3CXFQDN}}/webapi/{{AccessKey}}/parameter.get?name={parameter name}
{
"name": "VERSION",
"description": "Version",
"value": "20.0.5.384",
"type": 0
}Set 3CX system parameter. Use POST with JSON parameter
https://{{3CXFQDN}}/webapi/{{AccessKey}}/parameter.set
{
"result": true
}Delete 3CX system parameter(s)
https://{{3CXFQDN}}/webapi/{{AccessKey}}/parameters.del?name={parameter1,parameter2}
{
"result": "The parameter list has been removed"
}Pay attention. When creating an extension using WebAPI, the password complexity is not checked