Skip to main content
Skip table of contents

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. 


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.

  • 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. Details on the various endpoints are listed in the next section.


4. API Endpoints

ipSCAPE API Endpoints

What does this do?

Input

Old Endpoint(s)

Limitations

{{BaseURL}}/v3.0/activities/{activityId} → [GET]

Retrieves data for a single activity

Activity IDMANDATORY

/api/latest/activity/readactivitieslist

Endpoint currently only supports Inbound and Outbound Voice Campaigns

{{BaseURL}}/v3.0/activities → [GET]

Retrieves data for a list of activities based on input parameters up to 50 items

campaignIdOPTIONAL ; createdTimestampFrom OPTIONAL ; createdTimestampTo OPTIONAL ; activityTypeOPTIONAL

/api/latest/activity/readactivitieslist

Endpoint currently only supports Inbound and Outbound Voice Campaigns

{{BaseURL}}/v3.0/campaigns/statistics/inbound/{campaignId} → [GET]

Retrieves data for a single campaign

Campaign IDMANDATORY

/api/latest/campaign/readassignedagents; /api/latest/campaign/readassignedagents; /api/latest/campaign/readcalldetails; /api/latest/campaign/readcampaignstatistics; /api/latest/campaign/readqueuestatus

{{BaseURL}}/v3.0/media/metadata/recordings/{mediaId} → [GET]

Get a Call recording with associated metadata

Media IDMANDATORY

/api/latest/campaign/readcallrecording

{{BaseURL}}/v3.0/media/{mediaId} → [GET]

Downloads any media file

Media IDMANDATORY

{{BaseURL}}/v3.0/media/metadata/voicemails/{mediaId} → [GET]

Get a voicemail with associated metadata

Media IDMANDATORY

{{BaseURL}}/v3.0/leads → [POST]

Creates a new lead based on specific input data

{  "listId": 150,  "customerKey": "ABCD_1239",  "timezone": "Australia/Sydney",  "phone1": "+61289993154",  "phone2": "+61412463718",  "phone3": "",  "nextAttemptTimestamp": "2023-04-05T21:12:09+11:00",  "leadData": {}} MANDATORY

/lead/createlead

{{BaseURL}}/v3.0/leads/{leadId} → [DELETE]

Deletes a specified lead

Lead IDMANDATORY

/api/latest/lead/deletelead

{{BaseURL}}/v3.0/leads/{leadId} → [GET]

Retrieves data for a single lead

Lead IDMANDATORY

/api/latest/lead/readleaddetails

{{BaseURL}}/v3.0/leads/{leadId} → [PUT]

Updates data for a single lead

Lead IDMANDATORY
{  "listId": 150,  "customerKey": "ABCD_1239",  "timezone": "Australia/Sydney",  "phone1": "+61289993154",  "phone2": "+61412463718",  "phone3": "",  "nextAttemptTimestamp": "2023-04-05T21:12:09+11:00",  "leadData": {}} OPTIONAL

/api/latest/lead/updateleaddetails

{{BaseURL}}/v3.0/leads/lists/{listId} → [GET]

Retrieves data for a single lead list

Lead IDMANDATORY

/api/latest/lead/readleadslist

{{BaseURL}}/v3.0/leads → [GET]

Returns a list of leads based on input parameters, can return up to 50 items.

campaignIdOPTIONAL ; listId OPTIONAL ; uploadedTimestampFrom OPTIONAL ; uploadedTimestampTo OPTIONAL

/api/latest/lead/readlistslist

{{BaseURL}}/v3.0/leads/list → [GET]

Retrieves a list lead lists

Campaign IDMANDATORY

{{BaseURL}}/v3.0/dialler → [GET]

Returns a list of dialler calls based on input parameters, can return up to 50 items.

campaignIdOPTIONAL ; listId OPTIONAL ; uploadedTimestampFrom OPTIONAL ; uploadedTimestampTo OPTIONAL

/api/latest/campaign/readcallslist

{{BaseURL}}/v3.0/dialler/{attemptId} → [GET]

Retrieves data for a single dialer attempt

Attempt IDMANDATORY

{{BaseURL}}/v3.0/customer → [DELETE]

Removes all related data for a specified contact phone number (voice campaigns) or email address (email or chat campaigns).

Any removed data will be replaced with “GDPR”, for example in Calls:

image-20240214-055057.png

phoneNumberOPTIONAL*

emailAddressOPTIONAL*

*at least one of the above is required

Use caution when inputting with phone numbers as it is using a regex which can match numbers that are not an exact match.

{{BaseURL}}/v3.0/Campaigns/statistics/outbound/ → [GET]

Retrieve the statistics from a specified campaign such as Agents assigned/busy/paused, campaign activity status , created and last updated timestamps, and List details

CampaignIDMANDATORY

{{BaseURL}}/v3.0/agent/availability/ → [PUT]

Update an Agents' availability status ('Available' / ‘Unavailable’)

AgentIDMANDATORY

Placing an Agent into a custom unavailable state (pause reason) is not currently in scope for this endpoint


5. Errors

Error Type

Description

401

Ensure that the Authorisation Token and Secret Key entered is correct

404

Ensure that API URL is correctly formatted

To ensure stability of your application, the application is limited to 120 calls per minute.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.