Extension Management

Guide

How to Add, Edit and Delete Extensions or Contacts Using the HTTP API

Mr. VoIP's custom-built 3CX HTTP API lets you add, update and delete extensions and phonebook contacts from one place. This reference covers every operation, with request and response examples, field requirements and error codes.

Overview

Every call is an HTTP POST to your 3CX server's API endpoint. The operation is chosen with the action parameter, your security key goes in qsSecuritykey, and the data is sent as JSON in qsValue.

Base URL

https://your-3cx-server:8000/api.aspx

Replace your-3cx-server with your server address and YOUR_SECURITY_KEY with the key issued for your system.

Every request is checked against your security key before anything is added, updated, or deleted.
For every add or update, an email is sent to the extension's email address, as long as one is provided.
An extension number can't be changed after the extension is created.
Deleting an extension backs up its call recordings and voicemail automatically.

1. Add a single extension

Creates one extension. Extension number and first name are required.

POST URL

https://your-3cx-server:8000/api.aspx?action=addExt&qstype=1&qsSecuritykey=YOUR_SECURITY_KEY&qsValue={json}

Request body (qsValue)

{
  "sExtension": [
    {
      "ExtentionNumber": "xxxx",
      "EmailAddress": "",
      "FirstName": "xxxx",
      "LastName": "",
      "OutboundCallerID": ""
    }
  ]
}

Response — success

{"status":"Extension Created", "errorMessage":"", "errorCode":""}

Response — failure

{"message":"Authentication Token invalid", "errorCode":"INVALID_AUTH_ID"}

2. Add multiple extensions

Creates several extensions in one call by sending more than one object in the array.

POST URL

https://your-3cx-server:8000/api.aspx?action=addExt&qstype=1&qsSecuritykey=YOUR_SECURITY_KEY&qsValue={json}

Request body (qsValue)

{
  "mExtension": [
    {
      "ExtentionNumber": "xxxx",
      "EmailAddress": "",
      "FirstName": "xxxx",
      "LastName": "",
      "OutboundCallerID": ""
    },
    {
      "ExtentionNumber": "xxxx",
      "EmailAddress": "",
      "FirstName": "xxxx",
      "LastName": "",
      "OutboundCallerID": ""
    }
  ]
}

Response — success

{"status":"All Extension Created", "errorMessage":"", "errorCode":""}

Response — failure

{"message":"Authentication Token invalid", "errorCode":"INVALID_AUTH_ID"}

3. Update an extension

Changes an existing extension's details. The extension number identifies the record and cannot itself be changed.

POST URL

https://your-3cx-server:8000/api.aspx?action=updateExt&qstype=1&qsSecuritykey=YOUR_SECURITY_KEY&qsValue={json}

Request body (qsValue)

{
  "uExtension": [
    {
      "ExtentionNumber": "xxxx",
      "EmailAddress": "",
      "FirstName": "xxxx",
      "LastName": "",
      "OutboundCallerID": ""
    }
  ]
}

Response — success

{"status":"Extension Updated", "errorMessage":"", "errorCode":""}

4. Delete an extension

Removes an extension. Its call recordings and voicemail are backed up automatically.

POST URL

https://your-3cx-server:8000/api.aspx?action=deleteExt&qstype=1&qsSecuritykey=YOUR_SECURITY_KEY&qsValue={json}

Request body (qsValue)

{
  "dExtension": [
    { "ExtentionNumber": "xxxx" }
  ]
}

Response — success

{"status":"Extension Deleted", "errorMessage":"", "errorCode":""}

5. Add a contact

Creates a phonebook contact.

POST URL

https://your-3cx-server:8000/api.aspx?action=addPhonebook&qstype=1&qsSecuritykey=YOUR_SECURITY_KEY&qsValue={json}

Request body (qsValue)

{
  "sContact": [
    {
      "FirstName": "xxxx",
      "LastName": "xxxx",
      "PhoneNumber": "xxxx",
      "CompanyName": ""
    }
  ]
}

Response — success

{"status":"Contact Created", "errorMessage":"", "errorCode":""}

6. Update a contact

Changes a phonebook contact. RegisteredPhoneNumber is the contact's current number and identifies the record.

POST URL

https://your-3cx-server:8000/api.aspx?action=updatePhonebook&qstype=1&qsSecuritykey=YOUR_SECURITY_KEY&qsValue={json}

Request body (qsValue)

{
  "uContact": [
    {
      "FirstName": "xxxx",
      "LastName": "xxxx",
      "PhoneNumber": "xxxx",
      "CompanyName": "",
      "RegisteredPhoneNumber": "xxxx"
    }
  ]
}

Response — success

{"status":"Contact Updated", "errorMessage":"", "errorCode":""}

7. Delete a contact

Removes a phonebook contact by phone number.

POST URL

https://your-3cx-server:8000/api.aspx?action=deletePhonebook&qstype=1&qsSecuritykey=YOUR_SECURITY_KEY&qsValue={json}

Request body (qsValue)

{
  "dContact": [
    { "PhoneNumber": "xxxx" }
  ]
}

Response — success

{"status":"Contact Deleted", "errorMessage":"", "errorCode":""}

Field reference

Field names are case-sensitive and used exactly as shown, including the API's spelling of ExtentionNumber.

Extension fields

Field	Required	Description
ExtentionNumber	Yes	Unique extension identifier
EmailAddress	No	The user's email address
FirstName	Yes	The user's first name
LastName	No	The user's last name
OutboundCallerID	No	Outbound caller identification

Contact fields

Field	Required	Description
FirstName	Yes	The contact's first name
LastName	Yes	The contact's last name
PhoneNumber	Yes	The contact's phone number
CompanyName	No	The contact's company
RegisteredPhoneNumber	Update only	The contact's existing number, used to find the record

Error codes

Failed requests return an errorCode and message:

Code	Message	When it happens
INVALID_AUTH_ID	Authentication Token invalid	The security key is invalid
AUTH_ID_EXPIRED	Authentication Token expired	The security key has expired
INVALID_EXTENSION	Invalid Extension number	The extension is empty, illegal, or does not exist
EXTENSION_EXIST	Extension number already exist	You tried to add a duplicate extension
INVALID_EMAIL	Invalid Email Address	The email address is malformed
FNAME_INVALID	Invalid First name	The first name is empty
LNAME_INVALID	Invalid Last name	The last name is empty
PHONE_NUMBER_INVALID	Invalid Phone Number	The phone number is empty, illegal, or invalid
WEBSERVICE_ERROR	Exception detail	A server-side error; the message carries the exception detail
500	Internal Server error	A general server error

Want this for your call center?

Every Mr. VoIP tool is built around your existing 3CX setup — tell us what you're running and we'll scope it.

Get in touch