ipSCAPE API

Overview

ipSCAPE API provides a robust & flexible library of API’s to improve business integration and automation.​ ipSCAPE APIs can:​

• Improve efficiencies​

  • Further integrate data between your contact centre and other business applications for enhanced interactiveness​

  • Create Lead e.g. webform to a Lead in Dialler​

  • Update Lead Details​

• View Performance​

  • List of Transferred Calls​

  • Dial Attempts – for all phone numbers for a Lead​

  • Voicemail metadata - track important information such as when a call was received, who left the message, and how long the message was ​

  • Campaign performance – Estimated Wait Time, Agent Status​

Please note that API Support is out of the scope for Technical Support and will need Professional Services engagement. 

Already have an idea about API’s?

Check more information on our endpoints here: https://developer.onipscape.com/platform-api.html

1. What is an API?

An API, short for Application Programming Interface, is a software-to-software interface which provides a secure and standardised way for applications to communicate with each other and deliver the information or functionality requested with no user intervention.

2. How do APIs work?

APIs are sets of definitions or protocols that allow software components to communicate and interact with each other using basic sets of commands to deliver one application’s request to another and return a response in real time.

API Calls (Request methods)

An API call is the process of a client application submitting a request to a server's API and comprises everything that happens after the request is submitted, including when the API retrieves information from the server and delivers it back to the client (your ipSCAPE environment).

Method Types:

• GET: Retrieve data

• POST: Create new data

• PUT: Update or edit existing data

• DELETE: Delete data

What is an API token?

An API token in ipSCAPE is a unique identifier which acts like a username to authenticate calls to the API. The key is made up of a string of letters and numbers that identify the client. An ipSCAPE API Token will contain two Secret Keys.

What is an API key?

An API key is a unique identifier which acts like a password along with the API token to authenticate calls to an API. The key is made up of a string of letters and numbers that identify the client. The key can grant or deny that request based on the client’s access permissions, and track the number of requests made.

3. How to use ipSCAPE APIs

To use the ipSCAPE API, a Workspace administrator will first need to access the markup file, this can be found by accessing the following link (replace YOUR SUBDOMAIN.ipscape.com.au with your ipSCAPE tenant URL):

https://YOURSUBDOMAIN.ipscape.com.au/platform-api/platform-api.yaml

Ensure that the URL entered for the markup file is in lower-case.

• From here, copy and paste the entire contents of the YAML file into an API management application to visualise the endpoints.

  • The open-source option we use for this purpose is http://editor.swagger.io .

• If Swagger is used, paste the markup contents on the left-side of the screen. This should result in rendering the API markup. 

Note that there is a placeholder where the subdomain should be. Under server variables, change this to your ipSCAPE tenant subdomain, this should change the computed URL displayed as shown below.

In order to authenticate API requests, users must ensure that they have a valid API token. To view or configure Tokens:

• From the Workspace go to API tokens under the Integration menu

• For this menu to appear:

  • ipSCAPE Support enable the API token module, please raise a request with the Service Desk to enable

  • The User must have the correct User Role Permissions

• Once in the module, to create a new token, click the ‘Create new API token’ button in the top right-hand corner of the screen

• Enter a meaningful name and click ‘Save’. The new token will now appear in the list

• To view the token properties, click on the corresponding row. This will contain the newly generated ‘token’ and two ‘secret keys’.

This information allows an entity to poll the endpoints in the ipSCAPE environment, so it is important to keep it secure.
If for security reasons ensure to change the authorisation without downtime to the integration script, rotate the unused secret key, then copy the new key to the script making the call and update, then rotate the second key.

The secret keys are interchangeable. In other words, the following combinations will work:

• Token + secret key 1

• Token + secret key 2

• To complete the authorisation, go to the API management application or script

• Enter the token for the username and the secret key for the password

• If Authentication Type is required, choose Basic Authorization. See below screenshot from Swagger for an example:

• Once this is complete the API endpoints can be used. More details for different endpoints can be viewed here: ipSCAPE Platform API.