The Euphoria API is a basic Request and Response type environment. It cannot subscribe to telephone events and it’s not able to intercept an inbound call. You can use the API to poll through calls in the queue, get call detail records, and many other things. The data that is returned can be cached for up to 30 seconds, to eliminate load under frequent use.


API URL


The Euphoria API is hosted at the following URL:

https://api.euphoria.co.za/files/1010107057/api/Euphoria.Api.aspx


Usage Requirements

  • Requests must be HTTPS:
  • Must contain Tenant information, and an Authentication Key (see: Obtaining an API Key)
  • Must contain ActionName (see: API ActionName Reference)
  • XML must be wrapped in <XML></XML> Document Element

The API will require you to authenticate each request. No requests will be possible without the Tenant Name and Authentication Key(see: Obtaining an API Key)

Fiddler Web Debugger

 

It is highly advised that developers test XML Requests through Fiddler Web Debugger to ensure that the XML structures are correct and the responses returned are valid results before using it in the desired language.

 

Cached Responses

 

Every unique request is cached for 30 seconds, if a Tenant makes the same request within 30 seconds the API will return the previous result. This is a necessary feature to avoid abuse of the API and its interface to the Asterisk AMI. Some requests that do not return any data may not be cached and can be used as needed such as the Originate feature (initiating a call).

 

Request Limiting

 

Some requests such as Download Call Recording may be limited by 3 simultaneous request per Tenant. Once again this is to reduce the risk of abuse by initiating resource intensive API requests. 


API XML Structure

 

You will need to build the related code to pass XML to the API URL using the following XML structure. Typically the first section contains the login and authentication details relating to the account/tenant. This API services both residential, Trunk, Tenant and Extension requests.

 

Note: XML Nodes are case sensitive.

 

<?xml version="1.0" encoding="UTF-8"?>

<XML>

<Tenant>

    <Name>Your Tenant Name</Name>

    <Auth>Your-Auth-Key-goes-here</Auth>

</Tenant>

<ActionName>Your desired Action</ActionName>

...

Required and optional fields go here

...

</XML>


(also see: API ActionName Reference)


Error Handling

 

If the request returns with an error it will be structured as follows:

 

<?xml version="1.0" encoding="UTF-8"?>
<XML>
<Error>Description of error</Error>
</XML>

 

You should include an error checking level of code to handle the Error response. The system should never send back a 500 Error or typical HTTP error code. Unless the API server is unavailable the system will return with a 200 OK each time.


Error Reference

 

Input XML not loaded: The XML structure provided is incorrect, please check that the XML contains the header and the appropriate XML open en closing nodes.

 

No Document Element: No document element could be found. Please ensure that the case is correct.

 

Authorization Failed: Either the Name or Auth fields did not contain the correct information.

 

No Action Defined: No Action Name was provided.

 

Incorrect Input Parameters. Please check documentation: The required fields have not be provided, please check the Action Name reference page.

 

I'm sorry, connection to one or more of the databases failed: An internal error where the API failed to establish a connection to one or more of Euphoria’s Databases.

 

That username is not part of this Tenant: The required field passed does not contain information relating to this Tenant Name.

 

Permission Denied: The request does not have permission to access the ActionName.

 

Sip Server not found: Sip Server for the Tenant is unavailable.

 

Your previous request is pending: A second request was made before the first request has finished executing and returned any data.

 

Concurrent API Calls Exceeded: The amount of concurrent calls exceeds 3 for this specific request.

 

Action Name Not Found: The ActionName in the request does not exist.