X-on API

X-on API

Getting Started

Overview

The X-on API allows interaction with various parts of the Platform.

Authentication

You will be issued with an API Key that is used for authentication to the X-on API. Please contact X-on Support if you wish to revoke this key.

Your API Key must be provided in all requests to the API.

It is recommended to send the API Key via the Authorization header, but it will also be accepted in the query string or body, called api_token.

POST /api/v1/exampleMethod HTTP/1.1
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere

POST /api/v1/exampleMethod?api_token=YourAPIKeyHere HTTP/1.1
Host: platform.x-onweb.com

Input Parameters

Parameters are accepted via a range of methods. You can send them via the query string, as part of a JSON body, form encoded. All the following examples submit the same data.

POST /api/v1/exampleMethod?api_token=YourAPIKeyHere&parameter=value&parameter2=value2 HTTP/1.1
Host: platform.x-onweb.com

POST /api/v1/exampleMethod?parameter=value&parameter2=value2 HTTP/1.1
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere

POST /api/v1/exampleMethod HTTP/1.1
Host: platform.x-onweb.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 59

api_token=YourAPIKeyHere&parameter=value&parameter2=value2

POST /api/v1/exampleMethod HTTP/1.1
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
    "parameter": "value",
    "parameter2": "value2"
}

Resources

Individual Resource

When an individual resource is returned, it is presented in a data object.

{
    "data": {
       "id": 12345,
       "property": "example",
   }
}

Resources may also contain links to itself or related resources. These will be part of the data, in a property called links.

{
    "data": {
        "id": 12345,
        "property": "example",
        "links": [{
            "rel": "self",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345"
        }, {
            "rel": "type.relatedresource",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345/relatedresource"
        }, {
            "rel": "type.anotheresource",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345/anotherresource"
        }]
    }
}

API methods for individual resources may also accept an includes parameter to load related data, meaning the data can be loaded in one API request instead of multiple. In the example above, there are links to relatedresource and anotherresource. The includes parameter accepts a comma separated list of resources to load.

POST /api/v1/type/1234?includes=relatedresource,anotherresource HTTP/1.1
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
    "data": {
        "id": 12345,
        "property": "example",
        "links": [{
            "rel": "self",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345"
        }, {
            "rel": "type.relatedresource",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345/relatedresource"
        }, {
            "rel": "type.anotheresource",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345/anotherresource"
        }],
        "relatedresource": {
            "data": {
                "id": 3444,
                "prop": "value"
            }
        },
        "anotherresource": {
            "data": {
                "id": 45324,
                "property": "value",
                "another_prop": "another value"
            }
        }
    }
}

List Resources

Some API methods return a list of resources. These will provide an array of objects in data.

{
    "data": [{
        "id": 12345,
        "property": "example",
        "links": [{
            "rel": "self",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345"
        }, {
            "rel": "type.relatedresource",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345/relatedresource"
        }, {
            "rel": "type.anotheresource",
            "uri": "https://platform.x-onweb.com/api/v1/type/12345/anotherresource"
        }]
    }, {
        "id": 12346,
        "property": "example",
        "links": [{
            "rel": "self",
            "uri": "https://platform.x-onweb.com/api/v1/type/12346"
        }, {
            "rel": "type.relatedresource",
            "uri": "https://platform.x-onweb.com/api/v1/type/12346/relatedresource"
        }, {
            "rel": "type.anotheresource",
            "uri": "https://platform.x-onweb.com/api/v1/type/12346/anotherresource"
        }]
    }],
    "meta": {
        "pagination": {
            "total": 202,
            "count": 15,
            "per_page": 15,
            "current_page": 1,
            "total_pages": 14,
            "links": {
                "next": "https://platform.x-onweb.com/api/v1/type?page=2"
            }
        }
    }
}

The list will also return a meta object. Currently, this only contains pagination information to request more data. It will give the total number of records, and how many pages. It will also provide links to the previous or next page if appropriate.

To request additional pages, just use the links provided.

POST /api/v1/type?page=2 HTTP/1.1
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
    ...
}

Updating resources

Some resources can be updated using the HTTP PATCH method. This allows you to update individual properties of a resource.

API Reference

Calls

Click to Call

POST/api/v1/clicktocall

Schedule a Click to Call, where the Platform will contact the Target Agent (or an Agent in the group) before then dialling out to the destination. If the Agent does not answer, or the destination does not answer, then the call will wait for the retry interval before trying again. It will keep attempting until the Maximum Attempts has been reached, or the Expiry time passed.

Parameter Required Type Default Example Description
destination Yes String 01174960123

The destination phone number to ring after an agent answers the call. Format the number as it would be dialled from an actual phone.
target Yes String G0002

A user, or a group to target. Users must be prefixed with U, and groups must be prefixed with G. You can find your User and Group IDs from the Configuration Console.
enableRetries No boolean 1 false

Whether or not to enable retries.
maxAttempts No Integer 3

The number of attempts to contact the two parties. Must be between 1 and 10.
retryInterval No Integer 180

The number of seconds (between 60 and 600) to wait between retries.
whisper No String 1234

A PhonePresence prompt to play to the target once they answer the call and before attempting to dial the destination. The four digit prompt reference can be found in the Configuration Console.
callTime No Date & Time Now 2016-10-16T12:34:56+0000

An ISO 8601 formatted date time of when to start the phone call
expireTime No Date & Time One hour from the Call Time 2016-10-16T12:50:00+0000

An ISO 8601 formatted date time of when to give up attempting.
cli No string Default CLI for the target 03333320000

A valid CLI for the call to the destination. This CLI must be one of your Inbound Numbers.
cliPrivacy No boolean Default CLI privacy for the target false

Whether to enable CLI Privacy (withholding CLI) for the phone call to the destination. If used, the CLI parameter must also be provided.

 
POST /api/v1/clicktocall HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "destination": "01174960123",
  "target": "U0050"
}

Example with optional parameters

POST /api/v1/clicktocall HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "destination": "01174960123",
  "target": "U0050",
  "enableRetries": 1,
  "maxAttempts": 5,
  "retryInterval": 300
}

Returns the numeric Call ID. This Call ID is used throughout the X-on Platform, and can be used in other API methods to get more information.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "OK",
  "callId": 128547951
}

Call List

GET/api/v1/calls

Returns a list of calls that have finished. Without any parameters, it will return the last 24 hours of calls, ordered by end time descending. With parameters, you are able to search call logs with a number of filters.

Parameter Required Type Default Example Description
month No Integer 02
This parameter has been deprecated

It will still continue to work, but it is recommended to use other parameters instead.

The month (with leading zero) to view calls for. If year is not supplied, then the current year will be used.
year No Integer 2015
This parameter has been deprecated

It will still continue to work, but it is recommended to use other parameters instead.

The year to view calls for. Must be used with the month parameter
account_scope No string G0002

A user, or a group to limit the results to. Users must be prefixed with U, and groups must be prefixed with G. You can find your User and Group IDs from the Configuration Console. If a group is selected, it will also return any calls for members currently in the group.
start_date No Date (and Time) 2016-03-20

The starting date to return results from
end_date No Date (and Time) 2016-04-01 09:13:37

Used in conjunction with start_date to specify the end of the date range to return results
direction No INBOUND, OUTBOUND INBOUND

Return calls that were made in this direction
outcome No CALLER_CLEAR, VOICEMAIL, BUSY, NO_ANSWER, IVR_CLEAR CALLER_CLEAR

Return calls that ended with this outcome
internal No boolean false

Returns calls that are internal or external - true = internal, false = external
withheld No boolean false

Returns calls that included a withheld number
type No GROUP, PERSONAL, DIALLED, CALLBACK PERSONAL

Returns calls that matched the given type
caller.number No string 01174960123

Filter the call result by the caller's phone number
dialled.number No string 03333320000

Filter the call result by the phone number dialled
number No string 03333320000

Filter the call result by the phone number dialled, or the caller's phone number
name No string John Doe

Filter the call results by the name of the caller, dialled or the agent. This applies on top of any account_scope you may have supplied.

 
GET /api/v1/calls HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Viewing calls for October 2015

GET /api/v1/calls?year=2015&month=10 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Viewing calls between the 1st October 2015 and the 31st December 2015

GET /api/v1/calls?start_date=2015-10-01&end_date=2015-12-31 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Viewing inbound unanswered calls

GET /api/v1/calls?direction=INBOUND&outcome=NO_ANSWER HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Viewing inbound calls from 0333 332 0000 or 0333 332 0002

GET /api/v1/calls?direction=INBOUND&caller.number[]=03333320000&caller.number[]=03333320002 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Viewing outbound external calls

GET /api/v1/calls?direction=OUTBOUND&internal=false HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 128547951,
      "direction": "OUTBOUND",
      "caller": {
        "number": "+443333320000",
        "account": "G0123",
        "name": "X-on Inbound Number",
        "withheld": false
      },
      "dialled": {
        "number": "01174960123",
        "name": null
      },
      "agent": {
        "number": null,
        "account": "U0050",
        "name": "Jane Smith"
      },
      "group": {
        "account": null,
        "name": null
      },
      "type": "CALLBACK",
      "start_time": "2016-05-16T13:29:50+0000",
      "end_time": "2016-05-16T13:44:31+0000",
      "outcome": "CALLER_CLEAR",
      "reason": "NORMAL_CLEARING",
      "durations": {
        "ring": 3,
        "talk": 300,
        "ivr": 17,
        "hold": 3,
        "queue": 0
      },
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951"
        },
        {
          "rel": "call.queues",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/queues"
        },
        {
          "rel": "call.audio",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/audio"
        },
        {
          "rel": "call.actions",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/actions"
        }
      ]
    },
    {
      "id": 12345782,
      "direction": "INBOUND",
      "caller": {
        "number": "",
        "account": null,
        "withheld": true
      },
      "dialled": {
        "number": "+443333320000",
        "name": "X-on"
      },
      "agent": {
        "number": "299982009",
        "account": "U0017"
      },
      "group": {
        "account": "G0001",
        "name": "Sales"
      },
      "type": "GROUP",
      "start_time": "2016-05-14T12:29:50+0000",
      "end_time": "2016-05-14T12:44:31+0000",
      "outcome": "CALLER_CLEAR",
      "reason": "NORMAL_CLEARING",
      "durations": {
        "ring": 3,
        "talk": 300,
        "ivr": 17,
        "hold": 3,
        "queue": 17
      },
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calls/12345782"
        },
        {
          "rel": "call.queues",
          "uri": "https://platform.x-onweb.com/api/v1/calls/12345782/queues"
        },
        {
          "rel": "call.audio",
          "uri": "https://platform.x-onweb.com/api/v1/calls/12345782/audio"
        },
        {
          "rel": "call.actions",
          "uri": "https://platform.x-onweb.com/api/v1/calls/12345782/actions"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 202,
      "count": 15,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 14,
      "links": {
        "next": "https://platform.x-onweb.com/api/v1/calls?page=2"
      }
    }
  }
}
Parameter Type Example Description
id Integer 128547951

Call ID
direction INBOUND, OUTBOUND OUTBOUND

Direction of the call
caller
number string +443333320000

Phone number of the calling party
account string U0050

Account of the calling party (if known)
name string John Doe

The name of the calling party (if known)
withheld bool

Whether the caller had a withheld number
dialled
number string 01174960123

Phone Number dialled
name string

Name of the phone number dialled (if known)
agent
number string +443333320000

Phone number of the agent involved with the call
account string U0050

Account of the agent involved
name string Jane Smith

Name of the agent involved
group
account string G1119

Account of the last queue group involved in the phone call. To get more detailed information about the queues, use the Call Queues API method.
name string Support

Name of the last queue group
type GROUP, PERSONAL, DIALLED, CALLBACK GROUP

Type of the phone call.
start_time datetime 2016-05-16T13:29:50+0000

Time the call started
end_time datetime 2016-05-16T13:44:31+0000

Time the call ended
outcome CALLER_CLEAR, VOICEMAIL, BUSY, NO_ANSWER, IVR_CLEAR CALLER_CLEAR

The final outcome of the call
media_type audio audio

The media type of the call
is_internal bool 1

Whether or not the call was made and received within the same organisation
reason string NORMAL_CLEARING

The reason the call ended
durations
ring Integer

Ring Duration
talk Integer

How long the caller spoke to the other party
ivr Integer

How long the caller was in IVR (menus etc)
hold Integer

How long the caller was on Hold
queue Integer

How long the caller was in a queue

Call Information

GET/api/v1/calls/{callid}

Return information about one particular phone call. Important: This method will return a HTTP 409 error if you attempt to access a call that is ongoing.

Parameter Required Type Default Example Description
callid Yes Integer

Note: This parameter is required in the URL.

 12345782

The ID of the Call

 
GET /api/v1/calls/12345782 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": 128547951,
    "direction": "OUTBOUND",
    "caller": {
      "number": "+443333320000",
      "account": "G0123",
      "withheld": false
    },
    "dialled": {
      "number": "01174960123",
      "name": null
    },
    "agent": {
      "number": null,
      "account": "U0050"
    },
    "group": {
      "account": null,
      "name": null
    },
    "type": "CALLBACK",
    "start_time": "2016-05-16T13:29:50+0000",
    "end_time": "2016-05-16T13:44:31+0000",
    "outcome": "CALLER_CLEAR",
    "reason": "NORMAL_CLEARING",
    "durations": {
      "ring": 3,
      "talk": 300,
      "ivr": 17,
      "hold": 3,
      "queue": 0
    },
    "links": [
      {
        "rel": "self",
        "uri": "https://platform.x-onweb.com/api/v1/calls/128547951"
      },
      {
        "rel": "call.queues",
        "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/queues"
      },
      {
        "rel": "call.audio",
        "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/audio"
      },
      {
        "rel": "call.actions",
        "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/actions"
      }
    ]
  }
}

If you access an ongoing phone call, it will return a HTTP 409 error.

HTTP/1.1 409 Conflict
Content-Type: application/json

[
  {
    "message": "This call is still ongoing",
    "code": 409
  }
]
Parameter Type Example Description
id Integer 128547951

Call ID
direction INBOUND, OUTBOUND OUTBOUND

Direction of the call
caller
number string +443333320000

Phone number of the calling party
account string U0050

Account of the calling party (if known)
name string John Doe

The name of the calling party (if known)
withheld bool

Whether the caller had a withheld number
dialled
number string 01174960123

Phone Number dialled
name string

Name of the phone number dialled (if known)
agent
number string +443333320000

Phone number of the agent involved with the call
account string U0050

Account of the agent involved
name string Jane Smith

Name of the agent involved
group
account string G1119

Account of the last queue group involved in the phone call. To get more detailed information about the queues, use the Call Queues API method.
name string Support

Name of the last queue group
type GROUP, PERSONAL, DIALLED, CALLBACK GROUP

Type of the phone call.
start_time datetime 2016-05-16T13:29:50+0000

Time the call started
end_time datetime 2016-05-16T13:44:31+0000

Time the call ended
outcome CALLER_CLEAR, VOICEMAIL, BUSY, NO_ANSWER, IVR_CLEAR CALLER_CLEAR

The final outcome of the call
media_type audio audio

The media type of the call
is_internal bool 1

Whether or not the call was made and received within the same organisation
reason string NORMAL_CLEARING

The reason the call ended
durations
ring Integer

Ring Duration
talk Integer

How long the caller spoke to the other party
ivr Integer

How long the caller was in IVR (menus etc)
hold Integer

How long the caller was on Hold
queue Integer

How long the caller was in a queue

Call Audio

GET/api/v1/calls/{callid}/audio

Return a list of audio files associated with the callid. To retrieve the audio file, send a request to the self link provided in the response

Parameter Required Type Default Example Description
callid Yes Integer

Note: This parameter is required in the URL.

 12345782

The ID of the Call

 
GET /api/v1/calls/12345782/audio HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Download individual audio file

GET /api/v1/calls/12345782/audio/12132423 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 128547931,
      "user": "U0030",
      "file_size": 1302342,
      "type": "CALL_RECORDING",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/audio/128547931"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

When requesting an individual audio file, it will offer the file to download

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="128547931.mp3"
Content-Length: 1302342
Content-Type: audio/mpeg

"AudioFileDownload"
Parameter Type Example Description
id Integer 128547931

Audio ID
user string U0030

Account reference of the user who the audio is associated with
file_size Integer

File Size (in bytes) of the audio file
duration Integer

The duration of the audio (in seconds) if known.
read_time datetime

The date/time the voicemail was listened to. NULL if it hasn't been listened to yet.
type CALL_RECORDING, VOICEMAIL CALL_RECORDING

Audio type

Call Actions

GET/api/v1/calls/{callid}/actions

Returns any actions that were carried on for a phone call (e.g. save for later)

Parameter Required Type Default Example Description
callid Yes Integer

Note: This parameter is required in the URL.

 12345782

The ID of the Call

View the list of actions for a particular phone call

GET /api/v1/calls/12345782/actions HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

View an individual action

GET /api/v1/calls/12345782/actions/12132423 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 128547931,
      "time": "2016-06-02T14:41:15+0000",
      "type": "BUTTON",
      "data": "Actioned",
      "account": "U0077",
      "account_name": "John Doe",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/actions/128547931"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}
Parameter Type Example Description
id Integer 128547931

Action ID
time datetime 2016-05-16T13:29:50+0000

Time of the action
type string BUTTON

Action Type
data string

Associated data
account string U0077

Account of the agent who actioned the call
account_name string John Doe

The name of the Account

Call Actions

POST/api/v1/calls/{callid}/actions

Perform an action against a phone call (i.e. register that the call has been responded to)

Parameter Required Type Default Example Description
callid Yes Integer

Note: This parameter is required in the URL.

 12345782

The ID of the Call
action_by No string CUSTOMER UI

Text reference to record against this call action

Update call 12345782 as actioned

POST /api/v1/calls/12345782/actions HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Update call 12345782 as actioned by REPORT-UI

POST /api/v1/calls/12345782/actions HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "action_by": "REPORT-UI"
}


HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "OK"
}

Call Queues

GET/api/v1/calls/{callid}/queues

Returns any queues that the call was involved in

Parameter Required Type Default Example Description
callid Yes Integer

Note: This parameter is required in the URL.

 12345782

The ID of the Call

View the list of queues for a particular phone call

GET /api/v1/calls/12345782/queues HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

View an individual queue

GET /api/v1/calls/12345782/queues/12132423 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 128541337,
      "start_time": "2016-06-02T14:41:15+0000",
      "end_time": "2016-05-16T13:44:31+0000",
      "outcome": "Left",
      "account": "G0123",
      "account_name": "Support",
      "distribution_account": "G1000",
      "distribution_name": "Shared Agents",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/queues/128541337"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}
Parameter Type Example Description
id Integer 128541337

Queue ID
start_time datetime 2016-05-16T13:29:50+0000

Time the call joined the queue
end_time datetime 2016-05-16T13:44:31+0000

Time the call left the queue
outcome string Left

The outcome of the queue
account string G0123

Account of the queue
account_name string Support

The name of the Account
distribution_account string G1000

Account of the distribution queue. When Shared Queue Groups are configured, this will show the Shared Queue Group of the call, and the account value will be the Feeder Group.
distribution_name string Shared Agents

The name of the distribution queue

Call Menus

GET/api/v1/calls/{callid}/menus

Returns any menus that the call was involved in

Parameter Required Type Default Example Description
callid Yes Integer

Note: This parameter is required in the URL.

 12345782

The ID of the Call

View the list of menus for a particular phone call

GET /api/v1/calls/12345782/menus HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

View an individual menu

GET /api/v1/calls/12345782/menu/12132423 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 128541337,
      "start_time": "2016-06-02T14:41:15+0000",
      "end_time": "2016-05-16T13:44:31+0000",
      "name": "Main Menu",
      "choice": "3",
      "choice_name": "Support Queue",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/menus/128541337"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}
Parameter Type Example Description
id Integer 128541337

Menu ID
start_time datetime 2016-05-16T13:29:50+0000

Time the caller started the menu
end_time datetime 2016-05-16T13:44:31+0000

Time the caller left the menu
name string Main Menu

The name of the Menu
choice string 3

The Choice pressed by the caller. This can be any DTMF key (0-9 with */#), Failure (when they fail to enter anything), or HungUp
choice_name string Support Queue

The name of the next action after the choice has been selected

Call Wrap up Codes

GET/api/v1/calls/{callid}/wrapupcodes

Returns any wrap up codes that were set for the call

Parameter Required Type Default Example Description
callid Yes Integer

Note: This parameter is required in the URL.

 12345782

The ID of the Call

View the list of wrap up codes for a particular phone call

GET /api/v1/calls/12345782/wrapupcodes HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

View an individual wrap up code

GET /api/v1/calls/12345782/wrapupcodes/12132423 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 128541337,
      "end_time": "2016-05-16T13:44:31+0000",
      "code": "General Enquiry",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calls/128547951/wrapupcodes/128541337"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}
Parameter Type Example Description
id Integer 128541337

Wrapup Code ID
end_time datetime 2016-05-16T13:44:31+0000

Time the wrap up code was left
code string General Enquiry

The wrap up code

Call Wrap up Codes

POST/api/v1/calls/{callid}/wrapupcodes

Add a wrap up code to a call

Parameter Required Type Default Example Description
callid Yes Integer

Note: This parameter is required in the URL.

 12345782

The ID of the Call
code No string General Enquiry

Wrap up code to store against this call

Set a wrap up code of General Enquiry on call 12345782

POST /api/v1/calls/12345782/wrapupcodes HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "code": "General Enquiry"
}


HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "OK"
}

SMS

SMS List

GET/api/v1/sms

Returns a list of SMS that have been processed. Without any parameters, it will return the last 24 hours of messages, ordered by end time descending.

Parameter Required Type Default Example Description
start_date No Date (and Time) 2016-03-20

The starting date to return results from
end_date No Date (and Time) 2016-04-01 09:13:37

Used in conjunction with start_date to specify the end of the date range to return results
direction No INBOUND, OUTBOUND INBOUND

Return SMS messages in the direction specified
number No string 03333320000

Filter by the destination, or the originator
destination No string 07700900000

Filter by the destination number of the message
originator No string 03333320000

Filter by the originator of the message

 
GET /api/v1/sms HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Viewing SMS messages between the 1st October 2015 and the 31st December 2015

GET /api/v1/sms?start_date=2015-10-01&end_date=2015-12-31 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

Viewing inbound messages to or from either 0333 332 0000 or 0333 332 0002

GET /api/v1/sms?direction=INBOUND&number[]=03333320000&number[]=03333320002 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "delivered_time": "2019-06-20T15:56:21+00:00",
      "destination": "+447700900000",
      "direction": "OUTBOUND",
      "id": 1906153335884,
      "message": "You have a missed X-on call from 0117 496 0126, dated 20/06/2019 at 15:56:14. The number dialled was 0333 332 0000.",
      "originator": "80878",
      "outcome": "DELIVERED",
      "send_time": "2019-06-20T15:56:15+00:00",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/sms/1906153335884"
        }
      ]
    },
    {
      "delivered_time": "2019-06-19T14:50:39+00:00",
      "destination": "+447700900004",
      "direction": "OUTBOUND",
      "id": 1906153335885,
      "message": "You have won a prize!",
      "originator": "80878",
      "outcome": "DELIVERED",
      "send_time": "2019-06-20T00:13:37+00:00",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/sms/1906153335885"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 202,
      "count": 15,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 14,
      "links": {
        "next": "https://platform.x-onweb.com/api/v1/sms?page=2"
      }
    }
  }
}
Parameter Type Example Description
id Integer 190612241314

SMS ID
direction INBOUND, OUTBOUND OUTBOUND

Direction of the message
message string You have a missed call from...

The SMS Message
originator string +443333320000

Phone number of the party originating the message
destination string +447700900000

Phone number of the party receiving the message
send_time datetime 2016-05-16T13:29:50+0000

Time the SMS was sent
delivered_time datetime 2016-05-16T13:44:31+0000

Time the SMS was received by the phone
outcome DELIVERED, TIMEOUT, FAILED DELIVERED

The outcome of the SMS

SMS Information

GET/api/v1/sms/{smsid}

Return information about one particular SMS.

Parameter Required Type Default Example Description
smsid Yes Integer

Note: This parameter is required in the URL.

 1906153335885

The ID of the SMS

 
GET /api/v1/sms/1906153335885 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "delivered_time": "2019-06-19T14:50:39+00:00",
    "destination": "+447700900004",
    "direction": "OUTBOUND",
    "id": 1906153335885,
    "message": "You have won a prize!",
    "originator": "80878",
    "outcome": "DELIVERED",
    "send_time": "2019-06-20T00:13:37+00:00",
    "links": [
      {
        "rel": "self",
        "uri": "https://platform.x-onweb.com/api/v1/sms/1906153335885"
      }
    ]
  }
}
Parameter Type Example Description
id Integer 190612241314

SMS ID
direction INBOUND, OUTBOUND OUTBOUND

Direction of the message
message string You have a missed call from...

The SMS Message
originator string +443333320000

Phone number of the party originating the message
destination string +447700900000

Phone number of the party receiving the message
send_time datetime 2016-05-16T13:29:50+0000

Time the SMS was sent
delivered_time datetime 2016-05-16T13:44:31+0000

Time the SMS was received by the phone
outcome DELIVERED, TIMEOUT, FAILED DELIVERED

The outcome of the SMS

Send SMS

POST/api/v1/sms

Send an SMS

Please note that this method is only available to customers who have a Bulk SMS commercial agreement with X-on

Parameter Required Type Default Example Description
destination Yes string +447700900123

The Destination for the SMS. This can be a phone number, a User (starting with a 'U') or a Group (starting with a 'G') Account. If the destination is a Group, the message will be sent to every active member of the group (providing they have a mobile number).
originator Yes string X-on

Sender of the message, this parameter has a max character count of 11 characters. The originator must be agreed with us and fixed to your account.
body Yes string Hello, This is a free message no need to reply.

Contents of the actual message within the SMS, this parameter has a max character count of 160 characters

 
POST /api/v1/sms HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "destination": "+447700900123",
  "originator": "07700900000",
  "body": "Hello, This is a free message no need to reply."
}


POST /api/v1/sms HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "destination": "U0003",
  "originator": "X-on",
  "body": "Hello, This is a free message no need to reply."
}


POST /api/v1/sms HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "destination": "G0002",
  "originator": "X-on",
  "body": "Hello, This is a free message no need to reply."
}


HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "destinations": {
    "destination": "+447700900123",
    "ID": "74t82dh7-b9vc-6575-94bj-13yg63f5d35b",
    "status": "OK"
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "destinations": [
    {
      "destination": "+447700900321",
      "ID": "75d52gh7-b6nbb-6689-45bh-34th71g9d05b",
      "status": "OK"
    },
    {
      "desination": "+447700900123",
      "ID": "87h12fj9-g3eq-8471-05ih-83y63f5d35b",
      "status": "Invalid Number"
    },
    {
      "destination": "+447700900321",
      "ID": "67e37fy3-h6wo-5624-43lo-47th82u7p59j",
      "status": "OK"
    }
  ]
}

Users

User List

GET/api/v1/users

Returns a list of users

GET /api/v1/users HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "0003",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "status": "BREAK",
      "numbers": {
        "work": "200010003",
        "mobile": "+447700900123",
        "home": null,
        "temp": null
      },
      "active_number": {
        "type": "work",
        "number": "200010003"
      },
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/users/0003"
        }
      ]
    },
    {
      "id": "0007",
      "name": "Logged Out User",
      "email": "logged.out.user@example.com",
      "status": "LOGGED_OUT",
      "numbers": {
        "work": "200010007",
        "mobile": "+447700900321",
        "home": null,
        "temp": null
      },
      "active_number": {
        "type": null,
        "number": null
      },
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/users/0007"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 202,
      "count": 15,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 14,
      "links": {
        "next": "https://platform.x-onweb.com/api/v1/users?page=2"
      }
    }
  }
}
Parameter Type Example Description
id string 0003

User ID (Same as the Account reference, but without the leading 'U')
name string John Doe

The name of the user
email string john.doe@example.com

The email address of the user. This is used for logins and any email notifications
status AVAILABLE, DND, BREAK, WRAP_UP, OUTBOUND_CALLS, TASKS, LOGGED_OUT BREAK

The user's status
numbers
work string 200010003

The user's work number (null if not used)
mobile string +447700900123

The user's mobile number (null if not used)
home string +441174960123

The user's home number (null if not used)
temp string +443069990123

The user's temporary number (null if not used)
active_number
type work, mobile, home, temp work

The users currently defined active phone number (null is they don't have one set)
number string 200010003

The user's active number (null is they don't have one set)

User Information

GET/api/v1/users/{userid}

Returns information about a particular user

Parameter Required Type Default Example Description
userid Yes string

Note: This parameter is required in the URL.

 0003

The ID of the User

 
GET /api/v1/users/0003 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "0003",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "status": "BREAK",
    "numbers": {
      "work": "200010003",
      "mobile": "+447700900123",
      "home": null,
      "temp": null
    },
    "active_number": {
      "type": "work",
      "number": "200010003"
    },
    "links": [
      {
        "rel": "self",
        "uri": "https://platform.x-onweb.com/api/v1/users/0003"
      }
    ]
  }
}
Parameter Type Example Description
id string 0003

User ID (Same as the Account reference, but without the leading 'U')
name string John Doe

The name of the user
email string john.doe@example.com

The email address of the user. This is used for logins and any email notifications
status AVAILABLE, DND, BREAK, WRAP_UP, OUTBOUND_CALLS, TASKS, LOGGED_OUT BREAK

The user's status
numbers
work string 200010003

The user's work number (null if not used)
mobile string +447700900123

The user's mobile number (null if not used)
home string +441174960123

The user's home number (null if not used)
temp string +443069990123

The user's temporary number (null if not used)
active_number
type work, mobile, home, temp work

The users currently defined active phone number (null is they don't have one set)
number string 200010003

The user's active number (null is they don't have one set)

Update User Information

PATCH/api/v1/users/{userid}

Update user information

Parameter Required Type Default Example Description
userid Yes string

Note: This parameter is required in the URL.

 0003

The ID of the User
name No string Jon Doe

The new name for the user
status No AVAILABLE, DND, BREAK, WRAP_UP, OUTBOUND_CALLS, TASKS, LOGGED_OUT TASKS

The new status for the user
email No string jon.doe@example.com

The new email address for the user
active_number No work, mobile, home, temp work

The new active number for the user. Note: The user must have this number configured
numbers
work No string 200010003

The new work number for the user
mobile No string +447700900123

The new mobile number for the user
home No string +441174960123

The new home number for the user
temp No string 443069990123

The new temporary number for the user

 
PATCH /api/v1/users/0003 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "name": "Jon Doe"
}


PATCH /api/v1/users/0003 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "email": "jon.doe@example.com",
  "status": "TASKS"
}


PATCH /api/v1/users/0003 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "active_number": "work",
  "numbers": {
    "work": "200010003"
  }
}

If the request is successful, it will return an OK message.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK"
}

Groups

Group List

GET/api/v1/groups

Returns a list of groups. Phone calls will queue and target members of each group.

GET /api/v1/groups HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

View additional queue information

GET /api/v1/groups?includes=queue HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "0002",
      "name": "Sales Team",
      "distribution": "LONGEST_IDLE",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0002"
        },
        {
          "rel": "group.members",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0002/members"
        }
      ],
      "members": {
        "data": [
          {
            "user": "0003",
            "name": "John Doe",
            "priority": null,
            "active": true,
            "links": [
              {
                "rel": "self",
                "uri": "https://platform.x-onweb.com/api/v1/groups/0002/members/0003"
              },
              {
                "rel": "user",
                "uri": "https://platform.x-onweb.com/api/v1/users/0003"
              }
            ]
          },
          {
            "user": "0004",
            "name": "Jane Doe",
            "priority": null,
            "active": false,
            "links": [
              {
                "rel": "self",
                "uri": "https://platform.x-onweb.com/api/v1/groups/0002/members/0004"
              },
              {
                "rel": "user",
                "uri": "https://platform.x-onweb.com/api/v1/users/0004"
              }
            ]
          }
        ]
      }
    },
    {
      "id": "0012",
      "name": "Support Team",
      "distribution": "SIM_RING",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0012"
        },
        {
          "rel": "group.members",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members"
        }
      ],
      "members": {
        "data": [
          {
            "user": "0003",
            "name": "John Doe",
            "priority": 1,
            "active": true,
            "links": [
              {
                "rel": "self",
                "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members/0003"
              },
              {
                "rel": "user",
                "uri": "https://platform.x-onweb.com/api/v1/users/0003"
              }
            ]
          },
          {
            "user": "0007",
            "name": "Barry Scott",
            "priority": 1,
            "active": true,
            "links": [
              {
                "rel": "self",
                "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members/0007"
              },
              {
                "rel": "user",
                "uri": "https://platform.x-onweb.com/api/v1/users/0007"
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 202,
      "count": 15,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 14,
      "links": {
        "next": "https://platform.x-onweb.com/api/v1/groups?page=2"
      }
    }
  }
}

Group List with queue information included

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "0002",
      "name": "Sales Team",
      "distribution": "LONGEST_IDLE",
      "queue": {
        "data": {
          "max_size": 99,
          "max_wait": 3600,
          "oldest": "2021-08-24T15:39:35+00:00",
          "size": 3
        }
      },
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0002"
        },
        {
          "rel": "group.members",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0002/members"
        }
      ],
      "members": {
        "data": [
          {
            "user": "0003",
            "name": "John Doe",
            "priority": null,
            "active": true,
            "links": [
              {
                "rel": "self",
                "uri": "https://platform.x-onweb.com/api/v1/groups/0002/members/0003"
              },
              {
                "rel": "user",
                "uri": "https://platform.x-onweb.com/api/v1/users/0003"
              }
            ]
          },
          {
            "user": "0004",
            "name": "Jane Doe",
            "priority": null,
            "active": false,
            "links": [
              {
                "rel": "self",
                "uri": "https://platform.x-onweb.com/api/v1/groups/0002/members/0004"
              },
              {
                "rel": "user",
                "uri": "https://platform.x-onweb.com/api/v1/users/0004"
              }
            ]
          }
        ]
      }
    },
    {
      "id": "0012",
      "name": "Support Team",
      "distribution": "SIM_RING",
      "queue": {
        "data": {
          "max_size": 99,
          "max_wait": 3600,
          "oldest": null,
          "size": 0
        }
      },
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0012"
        },
        {
          "rel": "group.members",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members"
        }
      ],
      "members": {
        "data": [
          {
            "user": "0003",
            "name": "John Doe",
            "priority": 1,
            "active": true,
            "links": [
              {
                "rel": "self",
                "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members/0003"
              },
              {
                "rel": "user",
                "uri": "https://platform.x-onweb.com/api/v1/users/0003"
              }
            ]
          },
          {
            "user": "0007",
            "name": "Barry Scott",
            "priority": 1,
            "active": true,
            "links": [
              {
                "rel": "self",
                "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members/0007"
              },
              {
                "rel": "user",
                "uri": "https://platform.x-onweb.com/api/v1/users/0007"
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 202,
      "count": 15,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 14,
      "links": {
        "next": "https://platform.x-onweb.com/api/v1/groups?page=2"
      }
    }
  }
}
Parameter Type Example Description
id string 0002

Group ID (Same as the Account reference, but without the leading 'G')
name string Sales Team

The name of the group
distribution LONGEST_IDLE, LONGEST_TIME_SINCE_LAST_CALL, TOP_DOWN, COMPOUND, RANDOM, SIM_RING LONGEST_IDLE

The distribution pattern phone calls in the queue will take. See the Configuration Console for a description of each distribution type.
members include

The Group resource automatically includes the Group Members.
queue include

Show extra data with the current status of the queue

Group Information

GET/api/v1/groups/{groupid}

Returns information about a particular group.

Parameter Required Type Default Example Description
groupid Yes string

Note: This parameter is required in the URL.

 0002

The ID of the Group

 
GET /api/v1/groups/0012 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

View additional queue information

GET /api/v1/groups/0012?includes=queue HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "0012",
    "name": "Support Team",
    "distribution": "SIM_RING",
    "links": [
      {
        "rel": "self",
        "uri": "https://platform.x-onweb.com/api/v1/groups/0012"
      },
      {
        "rel": "group.members",
        "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members"
      }
    ],
    "members": {
      "data": [
        {
          "user": "0003",
          "name": "John Doe",
          "priority": 1,
          "active": true,
          "links": [
            {
              "rel": "self",
              "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members/0003"
            },
            {
              "rel": "user",
              "uri": "https://platform.x-onweb.com/api/v1/users/0003"
            }
          ]
        },
        {
          "user": "0007",
          "name": "Barry Scott",
          "priority": 1,
          "active": true,
          "links": [
            {
              "rel": "self",
              "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members/0007"
            },
            {
              "rel": "user",
              "uri": "https://platform.x-onweb.com/api/v1/users/0007"
            }
          ]
        }
      ]
    }
  }
]
Parameter Type Example Description
id string 0002

Group ID (Same as the Account reference, but without the leading 'G')
name string Sales Team

The name of the group
distribution LONGEST_IDLE, LONGEST_TIME_SINCE_LAST_CALL, TOP_DOWN, COMPOUND, RANDOM, SIM_RING LONGEST_IDLE

The distribution pattern phone calls in the queue will take. See the Configuration Console for a description of each distribution type.
members include

The Group resource automatically includes the Group Members.
queue include

Show extra data with the current status of the queue

Group Members

GET/api/v1/groups/{groupid}/members

Returns a list of members in a group

Parameter Required Type Default Example Description
groupid Yes string

Note: This parameter is required in the URL.

 0002

Group ID (Same as the Account reference, but without the leading 'G')

View the list of members in the group

GET /api/v1/groups/0002/members HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

View an individual member within a group

GET /api/v1/groups/0002/members/0007 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "user": "0007",
      "name": "Barry Scott",
      "priority": 1,
      "active": true,
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members/0007"
        },
        {
          "rel": "user",
          "uri": "https://platform.x-onweb.com/api/v1/users/0007"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

Viewing an individual member within the group

HTTP/1.1 200 OK
Content-Type: application/json

{
  "user": "0007",
  "name": "Barry Scott",
  "priority": 1,
  "active": true,
  "links": [
    {
      "rel": "self",
      "uri": "https://platform.x-onweb.com/api/v1/groups/0012/members/0007"
    },
    {
      "rel": "user",
      "uri": "https://platform.x-onweb.com/api/v1/users/0007"
    }
  ]
}
Parameter Type Example Description
user string 0007

User ID
name string Barry Scott

The name of the user
priority integer 3

The priority of the user within the group. Lower priorities get targeted first (1, then 2 etc.)
active boolean true

Whether the user is currently active within the group to receive calls

Add Group Member

PUT/api/v1/groups/{groupid}/members/{userid}

Add a user to a group

Parameter Required Type Default Example Description
groupid Yes string

Note: This parameter is required in the URL.

 0002

Group ID (Same as the Account reference, but without the leading 'G')
userid Yes string

Note: This parameter is required in the URL.

 0007

User ID (Same as the Account reference, but without the leading 'U')
priority No integer 7

The group priority for the user. Lower priorities get targeted first (1, then 2 etc.). Some group distribution types only allow one user per priority.
active No boolean true

Whether the user is active in the group. Only active members will get targeted for calls.

Add user 0007 to group 0002

PUT /api/v1/groups/0002/members/0007 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "priority": 3,
  "active": true
}

Add user 0007 to group 0002 without setting them active and accepting a default priority

PUT /api/v1/groups/0002/members/0007 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "message": "Adding user 0007 with priority 3"
}

Update Group Member

PATCH/api/v1/groups/{groupid}/members/{userid}

Update an existing user within a group

Parameter Required Type Default Example Description
groupid Yes string

Note: This parameter is required in the URL.

 0002

Group ID (Same as the Account reference, but without the leading 'G')
userid Yes string

Note: This parameter is required in the URL.

 0007

User ID (Same as the Account reference, but without the leading 'U')
priority No integer 7

The group priority for the user. Lower priorities get targeted first (1, then 2 etc.). Some group distribution types only allow one user per priority.
active No boolean true

Whether the user is active in the group. Only active members will get targeted for calls.

Update user 0007 within group 0002, and set their priority to 3

PATCH /api/v1/groups/0002/members/0007 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "priority": 3
}

Update user 0007 within group 0002 and set them inactive

PATCH /api/v1/groups/0002/members/0007 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "active": false
}


HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "message": "Updating existing user 0007 with priority 3"
}

Delete Group Member

DELETE/api/v1/groups/{groupid}/members/{userid}

Delete an existing user within a group

Parameter Required Type Default Example Description
groupid Yes string

Note: This parameter is required in the URL.

 0002

Group ID (Same as the Account reference, but without the leading 'G')
userid Yes string

Note: This parameter is required in the URL.

 0007

User ID (Same as the Account reference, but without the leading 'U')

Remove user 0007 within group 0002

DELETE /api/v1/groups/0002/members/0007 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK"
}

Contacts

Contact List

GET/api/v1/contacts

Returns a list of contacts or contact containers.

Parameter Required Type Default Example Description
type No string cn

Returned record type. For contacts use "cn" (default), For a list of available contact containers use "ou".
fields No array username

Specifies the fields to search against.
value No string John

Search term.

 
GET /api/v1/contacts HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "2",
      "dn": "cn=john doe,ou=users,ou=customer,ou=division,o=provider",
      "name": "John",
      "type": "cn",
      "username": "John Doe",
      "surname": "Doe",
      "givenname": "Dr John Doe",
      "email": "john.doe@company.com",
      "phone": "01728000000",
      "homephone": "",
      "mobile": "07700900000",
      "notes": "",
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/contacts/2"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1
    }
  }
}
Parameter Type Example Description
id string 2

Entry ID
dn string cn=john doe,ou=users,ou=customer,ou=division,o=provider

LDAP Distinguished Name
name string John

Entry name
type string cn

LDAP record type (cn, ou)
username string John Doe

Contact User Name. *included when type = cn.
surname string Doe

Contact Surname. *included when type = cn.
givenname string Dr John Doe

Contact Given Name. *included when type = cn.
email string john.doe@company.com

Contact Email Address. *included when type = cn.
phone string 01728000000

Contact Phone Number. *included when type = cn.
homephone string 01728000001

Contact Home Phone Number. *included when type = cn.
mobile string 07700900000

Contact Mobile Phone Number. *included when type = cn.
notes string Custom notes

Notes. *included when type = cn.
parentname string Company name

Contact Container Parent Name. *included when type = ou.

Contact Information

GET/api/v1/contacts/{id}

Returns information about a particular contact.

Parameter Required Type Default Example Description
id Yes string

Note: This parameter is required in the URL.

 2

The ID of the Contact

 
GET /api/v1/contacts/2 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "2",
      "dn": "cn=john doe,ou=users,ou=customer,ou=division,o=provider",
      "name": "John",
      "type": "cn",
      "username": "John Doe",
      "surname": "Doe",
      "givenname": "Dr John Doe",
      "email": "john.doe@company.com",
      "phone": "01728000000",
      "homephone": "",
      "mobile": "07700900000",
      "notes": "",
      "parentid": "1"
    }
  ]
}
Parameter Type Example Description
id string 2

Entry ID
dn string cn=john doe,ou=users,ou=customer,ou=division,o=provider

LDAP Distinguished Name
name string John

Entry name
type string cn

LDAP record type (cn, ou)
username string John Doe

Contact User Name. *included when type = cn.
surname string Doe

Contact Surname. *included when type = cn.
givenname string Dr John Doe

Contact Given Name. *included when type = cn.
email string john.doe@company.com

Contact Email Address. *included when type = cn.
phone string 01728000000

Contact Phone Number. *included when type = cn.
homephone string 01728000001

Contact Home Phone Number. *included when type = cn.
mobile string 07700900000

Contact Mobile Phone Number. *included when type = cn.
notes string Custom notes

Notes. *included when type = cn.
parentid string 1

ID of the entries parent

Add Contact

POST/api/v1/contacts

Add a contact

Parameter Required Type Default Example Description
name Yes string John

First name of the contact.
surname Yes string Doe

Surname of the contact.
parentid No string 7

Containing Parent ID. If not set, contact will be written into the default user container
givenname No string Dr John Doe

Given (Familiar/Display) name of the contact. If empty, will be populated with the name and surname values
email No string john.doe@company.com

Contact email address.
phone No string 01728000000

Contact phone number.
homephone No string 01728000001

Contact home phone number
mobile No string 07700900000

Contact mobile phone number.
notes No string Custom notes

Notes.

Add contact

POST /api/v1/contacts HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "name": "John",
  "surname": "Doe",
  "givenname": "Dr John Doe",
  "email": "john.doe@company.com",
  "phone": "01728000000",
  "homephone": "",
  "mobile": "",
  "notes": "Lorem Ipsum"
}


HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "id": 2,
  "message": "Contact record has been saved"
}

Update Contact

PATCH/api/v1/contacts/{id}

Update a contact

Parameter Required Type Default Example Description
id Yes string

Note: This parameter is required in the URL.

 2

Contact ID
name Yes string John

First name of the contact. Optional if givenname is provided.
surname Yes string Doe

Surname of the contact. Optional if givenname is provided.
givenname No string Dr John Doe

Given (Familiar/Display) name of the contact. If empty, will be populated with the name and surname values
email No string john.doe@company.com

Contact email address.
phone No string 01728000000

Contact phone number.
homephone No string 01728000001

Contact home phone number
mobile No string 07700900000

Contact mobile phone number.
notes No string Custom notes

Notes.

Update contact

PATCH /api/v1/contacts/2 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "name": "John",
  "surname": "Doe",
  "givenname": "Dr John Doe",
  "email": "john.doe@company.com",
  "phone": "01728000000",
  "homephone": "",
  "mobile": "",
  "notes": "Lorem Ipsum"
}


HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "id": 2,
  "message": "Contact record has been updated"
}

Delete Contact

DELETE/api/v1/contacts/{id}

Remove contact

Parameter Required Type Default Example Description
id Yes string

Note: This parameter is required in the URL.

 2

Contact ID

Remove contact 2

DELETE /api/v1/contacts/2 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK"
}

Calendars

Calendar List

GET/api/v1/calendars

Returns a list of calendars.

GET /api/v1/calendars HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 2,
      "name": "Main Calendar",
      "current_mode": {
        "id": 7,
        "name": "Lunch",
        "start_time": "2024-04-20T12:00:00+01:00",
        "is_override": false
      },
      "next_mode": {
        "id": 4,
        "name": "Open",
        "start_time": "2024-04-20T13:37:00+01:00",
        "is_override": true
      },
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calendars/2"
        },
        {
          "rel": "calendar.schedule",
          "uri": "https://platform.x-onweb.com/api/v1/calendars/2/schedule"
        }
      ]
    },
    {
      "id": 8320,
      "name": "Bypass Calendar",
      "current_mode": {
        "id": 2,
        "name": "Closed",
        "start_time": "2024-04-20T09:00:00+01:00",
        "is_override": false
      },
      "next_mode": null,
      "links": [
        {
          "rel": "self",
          "uri": "https://platform.x-onweb.com/api/v1/calendars/8320"
        },
        {
          "rel": "calendar.schedule",
          "uri": "https://platform.x-onweb.com/api/v1/calendars/8320/schedule"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 2,
      "per_page": 15,
      "current_page": 1,
      "total_pages": 1
    }
  }
}
Parameter Type Example Description
id Integer 2

Calendar ID
Name String Main Calendar

Calendar Name
current_mode

Nullable object showing the current mode
id Integer 7

Mode ID
name String Lunch

Mode Name
start_time datetime 2016-05-16T13:29:50+0000

Time the event started
is_override boolean false

Whether this mode has been overridden from the default calendar
next_mode

Nullable object showing the current mode
id Integer 4

Mode ID
name String Training

Mode Name
start_time datetime 2016-05-16T15:00:00+0000

Time the event will start
is_override boolean true

Whether this mode has been overridden from the default calendar

Calendar Information

GET/api/v1/calendars/{id}

Return information about one particular calendar

Parameter Required Type Default Example Description
id Yes Integer

Note: This parameter is required in the URL.

 820218

The ID of the Calendar

 
GET /api/v1/calendars/820218 HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": 820218,
    "name": "Main Calendar",
    "current_mode": {
      "id": 7,
      "name": "Lunch",
      "start_time": "2024-04-20T12:00:00+01:00",
      "is_override": false
    },
    "next_mode": {
      "id": 4,
      "name": "Open",
      "start_time": "2024-04-20T13:37:00+01:00",
      "is_override": true
    },
    "links": [
      {
        "rel": "self",
        "uri": "https://platform.x-onweb.com/api/v1/calendars/820218"
      },
      {
        "rel": "calendar.schedule",
        "uri": "https://platform.x-onweb.com/api/v1/calendars/820218/schedule"
      }
    ]
  }
}
Parameter Type Example Description
id Integer 2

Calendar ID
Name String Main Calendar

Calendar Name
current_mode

Nullable object showing the current mode
id Integer 7

Mode ID
name String Lunch

Mode Name
start_time datetime 2016-05-16T13:29:50+0000

Time the event started
is_override boolean false

Whether this mode has been overridden from the default calendar
next_mode

Nullable object showing the current mode
id Integer 4

Mode ID
name String Training

Mode Name
start_time datetime 2016-05-16T15:00:00+0000

Time the event will start
is_override boolean true

Whether this mode has been overridden from the default calendar

Calendar Modes

GET/api/v1/calendars/modes

Return the list of modes that the calendars can use

GET /api/v1/calendars/modes HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 7,
      "name": "Lunch"
    },
    {
      "id": 4,
      "name": "Open"
    },
    {
      "id": 2,
      "name": "Closed"
    }
  ]
}
Parameter Type Example Description
id Integer 7

Mode ID
name String Lunch

Mode Name

Calendar Schedule

GET/api/v1/calendars/{id}/schedule

Return the schedule about one particular calendar for the next 24 hours

Parameter Required Type Default Example Description
id Yes Integer

Note: This parameter is required in the URL.

 820218

The ID of the Calendar

 
GET /api/v1/calendars/820218/schedule HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "events": [
      {
        "id": 7,
        "name": "Lunch",
        "start_time": "2024-04-20T12:00:00+01:00",
        "is_override": false
      },
      {
        "id": 4,
        "name": "Open",
        "start_time": "2024-04-20T13:37:00+01:00",
        "is_override": true
      },
      {
        "id": 3,
        "name": "Closed",
        "start_time": "2024-04-20T17:30:00+01:00",
        "is_override": false
      }
    ],
    "links": [
      {
        "rel": "calendar",
        "uri": "https://platform.x-onweb.com/api/v1/calendars/820218"
      }
    ]
  }
}
Parameter Type Example Description
events

An array of events
id Integer 7

Mode ID
name String Lunch

Mode Name
start_time datetime 2016-05-16T13:29:50+0000

Time the event started
is_override boolean false

Whether this mode has been overridden from the default calendar

Set Calendar Override

POST/api/v1/calendars/{id}/override

Override a calendar to a particular mode

Parameter Required Type Default Example Description
id Yes Integer

Note: This parameter is required in the URL.

 324234

The ID of the Calendar
mode Yes Integer 2

The mode id to override this calendar with. Use the Calendar Modes endpoint to get the ids
type No PERMANENT, MIDNIGHT, MIDNIGHT_OR_NEXT_EVENT MIDNIGHT MIDNIGHT

When to end the override

Override calendar 324234 to Closed until midnight

POST /api/v1/calendars/324234/override HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json

{
  "mode": 2,
  "type": "MIDNIGHT"
}


HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "message": "Override will last until midnight.",
  "mode": {
    "id": 2,
    "name": "Closed"
  }
}

Delete Calendar Override

DELETE/api/v1/calendars/{id}/override

Remove an override for a calendar

Parameter Required Type Default Example Description
id Yes Integer

Note: This parameter is required in the URL.

 324234

The ID of the Calendar

 
DELETE /api/v1/calendars/324234/override HTTP/1.1 
Host: platform.x-onweb.com
Authorization: Bearer YourAPIKeyHere
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "message": "Calendar override removed"
}

Errors

If the API encounters an error, it will return a HTTP error code, and a description in the body.

401 Unauthorized

Your API Key is either missing, or invalid.

404 Not Found

If the data you requested can not be found, a JSON 404 page will be returned:

{
    "message": "No results found",
    "code": 404
}

422 Unprocessable Entity

The input you submitted failed validation. The body of the response will contain a JSON object listing the parameters with errors, and their error.

{
    "target": [
        "The target is invalid."
    ]
}

429 Too Many Attempts

There have been too many requests within a short period of time, and your access has been blocked temporarily.

All responses will contain headers highlighting the current state of the rate limiting.

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58

When the rate limiting has blocked access, an additional header will appear, saying how many seconds until the next request.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 56