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

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


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

{
  "data": [
    {
      "id": 128547951,
      "direction": "OUTBOUND",
      "caller": {
        "number": "+443333320000",
        "account": "G0123",
        "name": "X-on Inbound Number"
      },
      "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
      },
      "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)

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

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 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"
    },
    "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)

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

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 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.

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 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 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 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

SMS

Send SMS

POST/api/v1/sms

Send an SMS

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 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 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


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"
      }
    }
  }
}
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.


Group Information

GET/api/v1/groups/{groupid}

Returns information about a particular group.

Parameter Required Type Default Example Description
groupid Yes string 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


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.


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 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 1

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 0002

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

userid Yes string 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 0002

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

userid Yes string 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 0002

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

userid Yes string 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",
      "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.

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 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",
      "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.

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.

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": ""
}
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 2

Contact ID

name Yes string John

First name of the contact.

surname Yes string Doe

Surname of the contact.

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.

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": ""
}
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 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"
}

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