The OnSIP Admin API allows you to automate and/or integrate the administration of your OnSIP account.

Overview

Any task that can be completed in the OnSIP administrative portal can also be performed via the OnSIP Admin API, and then some. These tasks include: creating a user, retrieving information about an existing user, assigning a voicemail box, adding a phone number, and more. Requests are HTTP GET or HTTP POST, and response formats are (default) XML or JSON. The Admin API expects all data to be UTF-8 encoded.

The Admin API consists of a set of callable “Actions,” most of which require authentication with an administrative account. The credentials needed for authentication are the same as those used to access the OnSIP administrative portal, admin.onsip.com. See Creating a Session for an example of how this is done.

If you have any problems or requests, please visit our Help Center.

Hierarchy

The OnSIP Hierarchy:

Account
Accounts can have an unlimited number of Organizations.
Organization
An Organization is comprised of a single domain with an unlimited number of Users.
Users
A User represents an end user of the platform which is typically making or receiving calls.

Roles

In most cases, the “Account Administrator” takes on the responsiblity for managing the account (adding users, assigning extensions, setting up ACD Queues, etc.). The Account Administrator role is given by default to the user that created the account. It’s not possible to change the Account Administrator user, but it is possible to give other existing users in the account the Account Administror role. Please contact Support to do this.

Agent Administrator
This applies to OnSIP Agents only. The agent administrator has additional privileges, such as the ability to add an account as an agent.
Account Administrator
User with this role can edit their own account, organizations, and users.
Standard User
Users which can only edit their own information.
Anonymous User
This applies to GetOnSIP.com users only. These users have access to a very narrow subset of the API.

Authentication

Many methods require the user to be logged in. At present there is only one way to accomplish this. Users should request a SessionId token by authenticating using the SessionCreate action. The SessionId token should then be passed along with each request.

Request Format

The request format is simply a HTTP GET or a HTTP POST to the URL:

https://api.onsip.com/api

Every request requires an Action parameter to specify the requested action. All actions take a list of named parameters. The parameters and resulting responses for each action are listed on the action’s spec page.

For example, to request the Echo action, invoke like this:

https://api.onsip.com/api?Action=Echo&Foo=Bar

XML Response Format

The default response format is in the form of an XML document. The response document contains a single Response element. For example, a call to the Echo action returns this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?xml version="1.0" encoding="UTF-8"?>
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2006-12-18T00:36:49-05:00</DateTime>
      <Duration>2</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>Echo</Value>
        </Parameter>
        <Parameter>
          <Name>TestName</Name>
          <Value>TestValue</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <IsEstablished>false</IsEstablished>
    </Session>
  </Context>
  <Result>
    <Echo/>
  </Result>
</Response>

You can see a live example response here.

The RELAX NG schema for the response XML document is located here: jnctn.rng

Response Element

The Response element contains a Context element and a Result element.

A RELAX NG schema module for the Response element is located here: Response.rng

Context Element

The Context element contains information regarding the action taken, the request processed, and the session.

The Context element is a child of the Response element and contains

A RELAX NG schema module for the Context element is located here: Context.rng

Action Element

If the requested action completed successfully, the IsCompleted element will be true and the Response element will contain a Result element. Otherwise, the IsCompleted element will be false, the Response element will not contain a Result element, and the Action element may contain an Errors element detailing the reason for the failure. For example,

1
2
3
<Action>
  <IsCompleted>true</IsCompleted>
</Action>

A RELAX NG schema module for the Action element is located here: Action.rng

Request Element

If the parameters associated with the requested action validated, the IsValid element will be true. Otherwise, the IsValid element will be false and the Request element may contain an Errors element detailing reasons one or more parameters failed to validate. A request which fails to validate will never be completed. For example,

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<Request>
  <IsValid>true</IsValid>
  <DateTime>2006-12-18T00:36:49-05:00</DateTime>
  <Duration>2</Duration>
  <Parameters>
    <Parameter>
      <Name>Action</Name>
      <Value>Echo</Value>
    </Parameter>
    <Parameter>
      <Name>TestName</Name>
      <Value>TestValue</Value>
    </Parameter>
  </Parameters>
</Request>

A RELAX NG schema module for the Request element is located here: Request.rng

Session Element

If an authenticated session is established, the IsEstablished element will be true and the Session element will contain a SessionId element containing the session token. Otherwise, the IsValid element will be false. For example,

1
2
3
<Session>
  <IsEstablished>false</IsEstablished>
</Session>

A RELAX NG schema module for the Session element is located here: Session.rng

Result Element

The Result element contains information specific to the action taken and is only present if the action completed. Result elements are documented on the action’s spec page. Actions are listed on the API index page

A RELAX NG schema module for the Result element is located here: Result.rng.

Exception Element

If an exception occurs, a document like the following is returned:

1
2
3
4
5
6
<?xml version="1.0" encoding="UTF-8"?>
<Exception xmlns="http://www.jnctn.net/ns/rest/2006-01">
<![CDATA[
Textual description of the exception.
]]>
</Exception>

Exceptions should not occur. An Exception indicates an issue with the API. Please email any Exceptions received to support@onsip.com.

A RELAX NG schema module for the Exception element is located here: Exception.rng

JSON Response Format

JSON (JavaScript Object Notation) is a lightweight data format based on the object notation of the JavaScript language. It does not require JavaScript to read or write; it is easy to parse by any language and libraries and tools exist in many languages to handle JSON.

JSON Format Overview

JSON is a very simple text format based on JavaScript's object notation. The notation contains these basic elements:

For a complete description of JSON and its many uses, we suggest a visit to Douglas Crockford's JSON.org

How to Request JSON Output

For example, a call to the Echo action returns this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
 "Response":{
  "Context":{
   "Action":{
    "IsCompleted":"true"
   },
   "Request":{
    "IsValid":"true",
    "DateTime":"2006-12-27T23:18:16-05:00",
    "Duration":"1",
    "Parameters":{
     "Parameter":[
      {
       "Name":"Action",
       "Value":"Echo"
      },
      {
       "Name":"Output",
       "Value":"json"
      },
      {
       "Name":"TestName",
       "Value":"TestValue"
      }
     ]
    }
   },
   "Session":{
    "IsEstablished":"false"
   }
  },
  "Result":{
   "Echo":{
   }
  }
 }
}

You can see an example response here.

Callback Function

The Callback parameter (Callback=function) wraps the JSON output text in parentheses and a function name of your choosing.

Callback function names may only use upper and lowercase alphabetic characters (A-Z, a-z), numbers (0-9), the period (.), the underscore (_), and brackets ([ and ]). Brackets must be URL-encoded.

Results wrapped in callbacks look like this: ws_results( ...json output... );

Because JSON output is native JavaScript, you do not have to parse or evaluate the returned object in your callback function. You can immediately access the elements inside it, just as if you had passed an object reference to your ws_result function.

Callbacks are particularly useful for use with web service requests in client-side JavaScript. Normally web service requests using the XMLHttpRequest object run afoul of browser security restrictions that prevent files from being loaded across domains. This restriction requires you to proxy your requests on the server side or use server rewrites to trick the browser into thinking the web service data is coming from the same site as your web content.

Using JSON and callbacks, you can place the Admin API request inside a <script> tag, and operate on the results with a function elsewhere in the JavaScript code on the page. Using this mechanism, the JSON output from the Admin API request is loaded when the enclosing web page is loaded. No proxy or server trickery is required.

A simple working example is Click to Call.