First of all, what is a REST API server?
It’s nothing more than a simple web server – rather than outputting web pages for users to browse, it outputs data that is to be consumed by another computer application.
All of the information in your nCall database is available for interrogation via the nCall API Server.
How does the API module work?
Everything is done via performing HTTP actions on a URL. When you click on any URL, there is an underlying action that you are performing. For example, if you click on www.google.com, you are performing a GET action. If you complete a web form and click to submit, you are performing a POST action.
The API module works the same way. Each data table in the nCall database has been assigned a dedicated URL (e.g. CONTACTS, USERS, CALLS, MESSAGES etc.), and you can use actions to push, pull and modify data in these tables. You can use a GET action to pull data out. You can use a POST action to add a new row to a database table. You can also use PUT to modify data, and DELETE to (you guessed it!) delete data.
The API module will typically be accessed from the nCall Server using a dedicated port defined in the ncCallAPIserver.ini file (e.g. http://192.168.1.6:39123).
Example use case: retrieve the mobile number of contact ‘Jean’:
Each contact in nCall has a dedicated ID number (see this by displaying the ID column on the contact list in nCall). With this ID number, we can obtain information about the contact in a computer readable format. Jean’s ID is 1763, so we can write URL requests to obtain the information we require in JSON format.
Use username/password: test/test to access our demo nCall API Server*
The actual data returned depends on the fields that are listed in the ‘output_fields’ parameter in the URL in this case: ?output_fields=Firstname,Lastname,ID,Mobile
But what if we don’t know the ID of the contact that we want to request information for?
We can instead ask the API to only return results that have values matching our search terms. So rather than giving the contact ID number, we change the URL parameters to specify the value of the fields we want, for example ‘Firstname=Jean&Lastname=Barnet’ which give us all of the contacts who have a first name of Jean and a last name of Barnet:
If you provided even less information, such as just ‘Firstname’, you will receive all the contacts with the first name of ‘Jean’.
This shows just how simple it is to use the nCall REST API module. Full documentation of all of the URL end points and additional functions are available from the API itself:
The nCall API Server setup program also installs lots of example scripts written in various scripting languages, and the nCall User Group forum is a great place to ask questions if you need assistance.
What else can you do with the nCall API module?
Here is a list of some additional practical uses:
- Updating the nCall database automatically (e.g. when a new client signs up via your website)
- Pulling KPI data from the nCall database
- Create a wall board for your office
- Create reminders in nCall automatically via a web form
- Allow real-time monitoring of call analytics
- Allow clients to update their own details
- Enable 3rd party tools to pull and manipulate data from your nCall database, before pushing into another system
*You would not normally expose the API directly to the internet, this is only for demo reasons