API General Use

---

The Euphoria API is a basic Request and Response type environment. The data that is returned can be cached for up to 30 seconds, to eliminate load under frequent use.

Usage Requirements

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

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

Obtaining an API Key

• Log into the TMS
• Select the PBX the API needs to be on.
• Navigate to the API Manager. (If this option is not available, please contact the support company, and ask for the API Manager to be enabled.).
• Depending on which TMS is being used, the user will select either “API Auth Codes” or “API Manager”.
• Once loaded, the user can click on “Add API Key” and type in a relevant name for the API key.
• The TMS will then provide the user with a new API Authorization code.

Obtaining a Tenant Name

A Tenant name is a unique reference that is used to identify a specific PBX. Follow the below steps to obtain the Tenant Name:

• Log into the TMS but do not select the account. (Under an account there will either be a field called “Name” or “Account”. In this field there will be a unique one-word name which will be the Tenant Name).
• Log into the TMS, select the PBX the API should be used on.
• Navigate to Extension Manager
• Extensions
• Click on any extension
• Click on the “Send Password” button. (This will open a pop-up window information.)
• One of the fields will provide SIP username. The SIP username is made up of two parts that is separated with a dash (-): Extension Number - Tenant Name

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>

Error checking level of code should be inserted 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, check that the XML contains the header and the appropriate XML open enclosing nodes.

No Document Element:No document element could be found. 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 been provided, 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.

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.