API v1

Overview

Base URL

All resource URIs referenced in this documentation have the following base:

https://pbx.sipcentric.com/api/v1

All API requests should be made over HTTPS, rather than over HTTP.

Limits

To prevent individual applications from degrading the overall user experience, we limit the number of requests that can be made in any 60 minute window to 1200 per user.

This limit is not intended to restrict your creativity in any way, so if you need more please email support@sipcentric.com detailing your requirements. However, you are encouraged to cache information locally, wherever possible, and to design your application in a way which avoids unnecessary or repeat requests.

You can see your current status by checking the HTTP headers included in each response from us:

For example:

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 11

HTTP Methods

Instead of defining its own, arbitrary methods, the Sipcentric API utilizes four standard HTTP methods for interaction with all resources as follows:

GET

Retrieving a representation of a resource is as easy as GETting its URI. A simple way to test this is to type the URI of the desired resource into the address bar of your web browser.

Response Codes
Status Code Type Description
200 Ok Your request was successful and the response body contains the representation.
304 Not Modified The client's cached representation is still valid (conditional GET).
401 Unauthorized The credentials supplied are invalid, or insufficient to access the requested resource.
404 Not Found No resource was found at the requested location.
429 Too Many Requests You have reached your request limit for the current time window.
500 Server Error Something went wrong our end. If the problem persists please contact support@sipcentric.com.
POST

The POST method is used for creating resources. The representation of the object to be created should be contained within the request body, and the Content-Type header should be set according to the format you are sending, e.g. application/xml or application/json. See Response Formats for the formats we can accept.

Response Codes
Status Code Type Description
201 Created The request was successful and the response body contains a representation of the newly-created resource. The Location header will also be populated with the resource URI.
400 Bad Request There is a problem with your request and/or your data has failed validation. See the response body for more details.
401 Unauthorized The credentials supplied are invalid, or insufficient to create the resource.
404 Not Found The location to which you are POSTing does not exist.
405 Method Not Allowed The specified resource cannot be POSTed to.
429 Too Many Requests You have reached your request limit for the current time window.
500 Server Error The server has responded with an error. If the problem persists please contact support@sipcentric.com.
PUT

You should use the PUT method to update or modify resources. A representation of the object and its updated properties should be included in the body, and the Content-Type header set according to the format of the representation you are sending. See Response Formats for the formats we can accept.

Response Codes
Status Code Type Description
200 Ok The resource was successfully updated and the response body contains its new representation.
400 Bad Request There is a problem with your request and/or your data has failed validation. See the response body for more details.
401 Unauthorized The credentials supplied are invalid, or insufficient to update the resource.
404 Not Found The resource you are trying to update does not exist.
405 Method Not Allowed The specified resource is read-only and does not allow updates.
429 Too Many Requests You have reached your request limit for the current time window.
500 Server Error The server has responded with an error. If the problem persists please contact support@sipcentric.com.
DELETE

Finally, where supported, resources may be removed using the DELETE method. Please be careful though, as deleted resources cannot be restored afterwards!

Response Codes
Status Code Type Description
204 Deleted The resource was successfully deleted. The response body will be empty as there is no representation to return.
401 Unauthorized The credentials supplied are invalid, or insufficient to delete the resource.
404 Not Found The resource you are trying to remove does not exist.
405 Method Not Allowed The specified resource is read-only or not removable.
429 Too Many Requests You have reached your request limit for the current time window.
500 Server Error The server has responded with an error. If the problem persists please contact support@sipcentric.com.
Method Overloading

Not all HTTP libraries support the PUT and DELETE methods. However, it is possible to achieve the same outcome by using POST and including a _method query parameter in the request URL, with a value of either PUT or DELETE. For example, take the following DELETE request:

DELETE /customers/8425/numbers/44675

If your chosen library only supports GET or POST, this request can easily be simulated as follows:

POST /customers/8425/numbers/44675?_method=DELETE

Authentication

Authentication to the Sipcentric API occurs via HTTP Basic Authentication, with the same credentials as you would use to login to the web portal. Your credentials should be provided with every request.

Most HTTP libraries will handle Basic Authentication details automatically. To do it manually, include an Authorization header with a value of Basic <credentials> in every request, where “credentials” is a Base64-encoded version of the string "username:password". For example:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

As all Sipcentric accounts can have unlimited users, you may want to create a user specifically for the API, or for an application that uses the API.

Consumers of the API must authenticate at one of three levels:

Response Formats

We generally send (and receive) representations of objects in JSON format. There may be exceptions (in the case of sound files, for example), but these will be highlighted in the documentation specific to those resources.

For each request you should specify the Accept header, which we will evaluate and where possible, return a representation according to your preferred choice. For example:

Accept: application/json

Although including the Accept header in your request is the preferred method of specifying your desired representation format, it may not always be possible to include this header.

If an Accept header cannot be specified, you can append the desired type to the request URL instead, as in the example below.

https://pbx.sipcentric.com/api/v1/customers/1234/calls.json

This will override any Accept headers that have been added by your client and, in the above example, return a JSON representation.

List Resources

Some resources are in fact collections of other resources. For example, a list of all telephone numbers assigned to a particular customer account can be found by querying (GETting) the “phonenumbers” sub-resource. Similarly, new numbers can be added to the collection by POSTing to it.

Pagination

In some cases, lists of items can be quite long. To preserve bandwidth and reduce response time, lists are instead divided across multiple pages. To assist with pagination, a list resource will always contain the following information:

Property Description
totalItems The total number of items in the collection.
pageSize The number of items per page.
page The current page number.
items[] The items included in the current page.
prevPage A link to the previous page (if it exists).
nextPage A link to the next page (again, if it exists).

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers?pageSize=5&page=2
HTTP/1.1 200 OK

{
  "totalItems": 21,
  "pageSize": 5,
  "page": 2,
  "items": [
    {
      "type": "did",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/2468",
      ...
    },
    {
      "type": "did",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/1365",
      ...
    },
    {
      "type": "did",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/4775",
      ...
    },
    {
      "type": "did",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/2164",
      ...
    },
    {
      "type": "did",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers/3647",
      ...
    }
  ],
  "prevPage": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers?pageSize=5&page=1",
  "nextPage": "https://pbx.sipcentric.com/api/v1/customers/1234/phonenumbers?pageSize=5&page=3"
}

Query Parameters

Some list resources will have specific parameters that can be used to filter results (see individual resource documentation for details). However as a minimum, all list resources support the following query parameters:

Parameter Description
pageSize The number of items per page (default 20 / maximum 200).
page The page number to return (default 1).

For example, to limit results to 10 per page and return the second page:

GET /customers/8425/phonenumbers?pageSize=10&page=2

Data Formats

Dates & Times

All dates and times are formatted according to the ISO 8601 profile. For example:

2012-09-26T13:47:28Z

Customer Resources

Customers

Resource Information
Location /customers
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) customer
Additional Formats None

The customers resource is the starting point for most account-level operations. Each customer instance represents an account on the Sipcentric platform - it encapsulates a single company/PBX and all of its sub-resources.


{
  "type": "customer",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25",
  "created" : "2014-03-10T13:37:00.000+0000",
  "company": "Bloggs co",
  "firstName": "Fred",
  "lastName": "Bloggs",
  "telephone": "07557000000",
  "email": "contact@fredbloggs.com",
  "address1": "60 Cleveland St",
  "address2": "Fitzrovia",
  "city": "London",
  "postcode": "W1T 4JZ",
  "links": {
    "callBundles" : "https://pbx.sipcentric.com/api/v1/customers/25/callbundles",
    "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings",
    "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook",
    "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals",
    "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints",
    "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers",
    "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms",
    "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus",
    "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls",
    "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds",
    "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids"
  }
}
Type: customer
Property Description
type
required
The resource type ("customer").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
company
required
Name of the company on the account.
String
firstName
required
Primary contact first name.
String
lastName
required
Primary contact last name.
String
telephone
required
Primary contact telephone number.
String
email
required
Primary contact email address.
String
address1
required
Primary location address line 1.
String
address2
optional
Primary location address line 2.
String
city
required
Primary location town/city.
String
postcode
required
Primary location postcode.
String
links[]
read-only
A collection of links to related sub-resources.
Array
List customers

GET /customers

Lists all customer accounts to which the authenticating user has access. When authenticated as an extension user or a company admin, this will only return their own account. However, when authenticated as a reseller, all customer accounts owned by that reseller will be returned.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers
HTTP/1.1 200 OK

{
  "totalItems": 1,
  "pageSize": 1,
  "page": 1,
  "items": [
    {
      "type": "customer",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25",
      "created" : "2014-03-10T13:37:00.000+0000",
      "company": "Bloggs co",
      "firstName": "Fred",
      "lastName": "Bloggs",
      "telephone": "07557000000",
      "email": "contact@fredbloggs.com",
      "address1": "60 Cleveland St",
      "address2": "Fitzrovia",
      "city": "London",
      "postcode": "W1T 4JZ"
    }
  ]
}
Get customer

GET /customers/{customerId}

Returns a single customer instance, providing the user is allowed access to that customer. In the case of company admin/extension users, the special ID of me can also be used to return the account to which the current user belongs.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/me
HTTP/1.1 200 OK

{
  "type": "customer",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25",
  "created" : "2014-03-10T13:37:00.000+0000",
  "company": "Bloggs co",
  "firstName": "Fred",
  "lastName": "Bloggs",
  "telephone": "07557000000",
  "email": "contact@fredbloggs.com",
  "address1": "60 Cleveland St",
  "address2": "Fitzrovia",
  "city": "London",
  "postcode": "W1T 4JZ",
  "links": {
    "callBundles" : "https://pbx.sipcentric.com/api/v1/customers/25/callbundles",
    "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings",
    "phoneBook": "https://pbx.sipcentric.com/api/v1/customers/25/phonebook",
    "timeIntervals": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals",
    "endpoints": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints",
    "phoneNumbers": "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers",
    "sms": "https://pbx.sipcentric.com/api/v1/customers/25/sms",
    "creditStatus": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus",
    "calls": "https://pbx.sipcentric.com/api/v1/customers/25/calls",
    "sounds": "https://pbx.sipcentric.com/api/v1/customers/25/sounds",
    "outgoingCallerIds": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids"
  }
}

Phone Book

Resource Information
Location /customers/{customerId}/phonebook
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
POST
DELETE
PUT
JSON Representation(s) phonebookentry
Additional Formats None

The phonebook sub-resource allows users to read and organize an account's shared phone book entries. Each entry is represented by a phonebookentry.

{
  "type" : "phonebookentry",
  "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773",
  "created" : "2014-03-10T13:38:00.000+0000",
  "name" : "Sipcentric",
  "phoneNumber" : "01212854400",
  "speedDial" : 5
}
Type: phonebookentry
Property Description
type
required
The resource type ("phonebookentry").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
name
required
Full name of the contact.
String
phoneNumber
required
Phone number of the contact.
String
speedDial
optional
Assigned speed-dial for this contact (1-9999).
Integer
List phone book entries

GET /customers/{customerId}/phonebook

Return a list of every phonebookentry on the customer account.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=1
HTTP/1.1 200 OK

{
  "totalItems" : 18,
  "pageSize" : 2,
  "page" : 1,
  "items" : [ 
    {
      "type" : "phonebookentry",
      "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716",
      "created" : "2014-03-10T13:37:00.000+0000",
      "name" : "Fred Mobile",
      "phoneNumber" : "07902000000",
      "speedDial" : 3
    }, {
      "type" : "phonebookentry",
      "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773",
      "created" : "2014-03-10T13:38:00.000+0000",
      "name" : "Sipcentric",
      "phoneNumber" : "01212854400"
    }
  ],
  "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook?pageSize=2&page=2"
}
Read phone book entry

GET /customers/{customerId}/phonebook/{entryId}

Returns the instance of an individual phonebookentry.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773
HTTP/1.1 200 OK

{
  "type" : "phonebookentry",
  "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonebook/773",
  "created" : "2014-03-10T13:38:00.000+0000",
  "name" : "Sipcentric",
  "phoneNumber" : "01212854400"
}

Create phone book entry

POST /customers/{customerId}/phonebook

To create a new phone book entry, a representation of a phonebookentry must be POSTed to the phonebook resource. The newly created phonebookentry representation will then be included in the body of the response.

Example request:

POST https://pbx.sipcentric.com/api/v1/customers/25/phonebook

{
  "type" : "phonebookentry",
  "name" : "Fred Mobile",
  "phoneNumber" : "07902000000",
  "speedDial" : 4
}
HTTP/1.1 201 Created

{
  "type": "phonebookentry",
  "uri": "http://pbx.sipcentric.com/api/v1/customers/25/phonebook/716",
  "created" : "2014-03-10T13:38:00.000+0000",
  "name": "Fred Mobile",
  "phoneNumber": "07902000000",
  "speedDial": 4
}
Update phone book entry

PUT /customers/{customerId}/phonebook/{entryId}

To update a phonebookentry, a representation of the updated phonebookentry must be PUT to that instance resource. The updated phonebookentry representation will then be returned in the body of the response.

Example request:

PUT https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716

{
  "type" : "phonebookentry",
  "name" : "Fred Mobile",
  "phoneNumber" : "07825000000",
  "speedDial" : 12
}
HTTP/1.1 200 OK

{
  "type": "phonebookentry",
  "uri": "http://pbx.sipcentric.com/api/v1/customers/25/phonebook/716",
  "created" : "2014-03-10T13:38:00.000+0000",
  "name": "Fred Mobile",
  "phoneNumber": "07825000000",
  "speedDial": 12
}
Delete phone book entry

DELETE /customers/{customerId}/phonebook/{entryId}

To delete a phonebookentry, a DELETE request must be made to the instance resource.

DELETE https://pbx.sipcentric.com/api/v1/customers/25/phonebook/716
HTTP/1.1 204 No Content

SMS

Resource Information
Location /customers/{customerId}/sms
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
POST
JSON Representation(s) smsmessage
Additional Formats None

The SMS sub-resource contains a record of every SMS message sent or received on the account, each item represented by a single smsmessage.

{
  "type" : "smsmessage",
  "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368",
  "created" : "2014-03-10T13:37:00.0000+0000",
  "direction" : "OUT",
  "from" : "01212854400",
  "to" : "07902000000",
  "body" : "Hey, this API is awesome!",
  "sendStatus" : "SENT",
  "deliveryStatus" : 1,
  "cost" : 0.1
}
Type: smsmessage
Property Description
type
required
The resource type ("smsmessage").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
direction
read-only
Direction of the message.
Enum: IN, OUT
from
required
Name or phone number of the sender.
String
to
required
Phone number of the recipient.
String
body
required
The message body.
String
sendStatus
read-only
The send status of an outgoing message.
Enum: PENDING, SENT, FAILED
deliveryStatus
read-only
The delivery status of an outgoing message (where available):
1 = Delivered to handset
2 = Rejected from handset
4 = Buffered in transit (phone probably off / out of reception)
8 = Accepted by SMS carrier
16 = Rejected by SMS carrier
Integer
cost
read-only
Message cost in GBP.
Float
List SMS messages

GET /customers/{customerId}/sms

Returns a list of every smsmessage on the account.

GET https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=1
HTTP/1.1 200 OK

{
  "totalItems": 188,
  "pageSize": 2,
  "page": 1,
  "items":  [
     {
      "type": "smsmessage",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/253369",
      "created" : "2014-03-10T13:38:00.000+0000",
      "direction": "IN",
      "from": "07902000000",
      "to": "01212854400",
      "body": "I know, it's great!",
      "cost": 0.0
    }, {
      "type": "smsmessage",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368",
      "created" : "2014-03-10T13:37:00.000+0000",
      "direction": "OUT",
      "from": "01212854400",
      "to": "07902000000",
      "body": "Hey, this API is awesome!",
      "sendStatus": "SENT",
      "deliveryStatus": 1,
      "cost": 0.1
    } ],
  "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/sms?pageSize=2&page=2"
}
Get SMS Message

GET /customers/{customerId}/sms/{smsId}

Returns the instance of a specific smsmessage.

GET https://pbx.sipcentric.com/api/v1/customers/25/sms/253368
HTTP/1.1 200 OK

{
  "type" : "smsmessage",
  "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368",
  "created" : "2014-03-10T13:37:00.0000+0000",
  "direction" : "OUT",
  "from" : "01212854400",
  "to" : "07902000000",
  "body" : "Hey, this API is awesome!",
  "sendStatus" : "SENT",
  "deliveryStatus" : 1,
  "cost" : 0.1
}
Send SMS

POST /customers/{customerId}/sms

To send a new SMS, simply POST a representation of a new smsmessage to the list resource. If successful, a representation of the newly created smsmessage will be returned in the body of the response.

POST https://pbx.sipcentric.com/api/v1/customers/25/sms

{
  "type": "smsmessage",
  "to": "07902000000",
  "from": "01212854400",
  "body": "Hey, this API is awesome!"
}
HTTP/1.1 201 Created

{
  "type": "smsmessage",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/sms/253368",
  "direction": "OUT",
  "from": "01212854400",
  "to": "07902000000",
  "body": "Hey, this API is awesome!",
  "sendStatus": "SENT",
  "cost": 0.1
}

Calls

Resource Information
Location /customers/{customerId}/calls
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
POST
JSON Representation(s) call
Additional Formats text/csv

The calls sub-resource can be used to fetch the call history of an account, as well as to originate new calls. Each item is represented by a call.

The scope of a call can be:

{
  "type": "call",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592317",
  "created" : "2014-03-10T13:37:00.000+0000",
  "scope": "EXTERNAL",
  "direction": "IN",
  "from": "07557000000",
  "to": "Sales Group <500>",
  "callStarted": "2014-03-10T13:37:00.000+0000",
  "outcome": "NO_ANSWER",
  "duration": 0,
  "cost": 0,
  "callId": "ast01-1400142051.1562723",
  "linkedId": "ast01-1400142051.1562723",
  "links": {
    "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1400142051.1562723"
  }
}
Type: call
Property Description
type
required
The resource type ("call").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
scope
read-only
The scope of the call (see above for details).
Enum: LOCAL, DOMAIN, EXTERNAL
direction
read-only
Direction of the call.
Enum: IN, OUT
from
required
The name and/or phone number of the caller.
String
to
required
The name and/or phone number of recipient.
String
callStarted
read-only
UTC time when the call started (ISO8601 format).
String
outcome
read-only
The final outcome of the call.
Enum: ANSWERED, NO_ANSWER, BUSY, FAILED
duration
read-only
The duration of the call in seconds.
Integer
cost
read-only
The cost of the call in GBP.
Float
callId
read-only
A unique ID for this call or call leg.
String
linkedId
read-only
This ID is the same across all legs of an end-to-end call and can be used to group those multiple parts together. In an end-to-end call with multiple hops, the value of "linkedId" will always be equal to the "callId" of the first call in the chain.
String
links[]
read-only
A collection of links to related sub-resources.
Array
Get call history

GET /customers/{customerId}/calls

Making a GET request to the list resource will return a history of the calls made/received on an account. The returned list will contain a collection of call representations and may be filtered using the following (optional) query parameters:

Query String Parameters Type Description
createdAfter String Include only records created after the specified. date/time
createdBefore String Include only records created before the specified. date/time
startedAfter String Include only records started after the specified. date/time
startedBefore String Include only records started before the specified. date/time
from String Include only calls from a specific number. Currently supports exact match only (no wildcards).
to String Include only calls to a specific number. Currently supports exact match only (no wildcards).
direction String Include only calls in a specific direction (in/out).
includeLocal Boolean Whether or not to include local (internal) calls. Default is 'false'. Note: only the outbound record is included for calls between endpoints, as the inbound record would be an exact replica.
GET https://pbx.sipcentric.com/api/v1/customers/25/calls?createdAfter=2014-03-10T13:30:00Z&pageSize=2&page=1
HTTP/1.1 200 OK

{
  "totalItems": 23686,
  "pageSize": 2,
  "page": 1,
  "items": [
    {
      "type": "call",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592432",
      "created" : "2014-03-10T13:47:05.000+0000",
      "scope": "EXTERNAL",
      "direction": "IN",
      "from": "07557000000",
      "to": "Sales Group <500>",
      "callStarted": "2014-03-10T13:46:35.000+0000",
      "outcome": "NO_ANSWER",
      "duration": 0,
      "cost": 0,
      "callId": "ast01-1400142051.1562723",
      "linkedId": "ast01-1400142051.1562723",
      "links": {
        "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1400142051.1562723"
      }
    }, {
      "type": "call",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25/calls/7592134",
      "created" : "2014-03-10T13:37:00.000+0000",
      "scope": "EXTERNAL",
      "direction": "OUT",
      "from": "Greg Sanderson <103>",
      "to": "07557000000",
      "callStarted": "2014-03-10T13:35:51.000+0000",
      "outcome": "ANSWERED",
      "duration": 60,
      "cost": 0.09,
      "callId": "ast01-1401721105.2847099",
      "linkedId": "ast01-1401721105.2847099",
      "links": {
        "recordings": "https://pbx.sipcentric.com/api/v1/customers/25/recordings?linkedId=ast01-1401721105.2847099"
      }
    } ],
  "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/calls?pageSize=2&page=2"
}
Originate call

POST /customers/{customerId}/calls

To originate a new call, you should POST a new call representation containing the properties shown below, to the calls list resource.

Example request:

POST https://pbx.sipcentric.com/api/v1/customers/25/calls

{
  "type": "call",
  "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1234",
  "to": "07902000000"
}
HTTP/1.1 200 OK

In the above example, a connection will first be established with the specified local endpoint ("endpoint"). We will then attempt to place a call to the remote destination ("to") and finally bridge the two together.

Sounds

Resource Information
Location /customers/{customerId}/sounds
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) music
prompt
Additional Formats audio/wav

The sounds sub-resource is a container for all sound files that have been added to an account. A sound file is in itself an abstract type and as such, each instance is represented by one of the concrete sub-types detailed below.

Important: once a sound of a particular type has been created, its type cannot be changed - instead, it must be removed and re-added.

Sound Types
Prompt

Represents a voice greeting or announcement and can be played, for example, on entry to a call queue or to give instructions about which keys to press in an IVR.

Music

Represents music which can be played when a caller is placed on hold or is waiting in a queue.

The properties of each sound type are listed below.

Type: prompt
Property Description
type
required
The resource type ("prompt").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
name
read-only
Name of the prompt.
String
size
read-only
Size of the underlying file in bytes.
Long
Type: music
Property Description
type
required
The resource type ("music").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
name
read-only
Name assigned to the music.
String
size
read-only
Size of the file in bytes.
Integer
enabled
required
Whether or not the music is enabled and will play.
Boolean
List sounds

GET /customers/{customerId}/sounds

Returns all sounds, optionally filtered by the following query parameters:

Query String Parameters Type Description
type String Include only a specific type of sound file (prompt/music)

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=1
HTTP/1.1 200 OK

{
  "totalItems" : 6,
  "pageSize" : 2,
  "page" : 1,
  "items" : [ {
    "type" : "prompt",
    "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1046",
    "created" : "2014-03-10T13:38:00.0000+0000",
    "name" : "thank-you-for-calling",
    "size" : 129612
  }, {
    "type" : "prompt",
    "uri" : "https://pbx.sipcentric.com/api/v1/customers/5/sounds/1035",
    "created" : "2014-03-10T13:37:00.0000+0000",
    "name" : "calls-may-be-recorded",
    "size" : 69426
  } ],
  "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds?pageSize=2&page=2"
}
Get sound

GET /customers/{customerId}/sounds/{soundId}

Returns the instance of a specific sound file.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035
HTTP/1.1 200 OK

{
  "type" : "prompt",
  "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/sounds/1035",
  "created" : "2014-03-10T13:37:00.0000+0000",
  "name" : "calls-may-be-recorded",
  "size" : 69426
}

It is also possible to fetch a copy of the audio file itself, by including the Accept header:

Accept: audio/wav

See Response Formats for more information.

Recordings

Resource Information
Location /customers/{customerId}/recordings
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) recording
Additional Formats audio/wav

The recordings sub-resource provides a way to retrieve and manage the call recordings which are currently stored on an account. Each recording representation contains a set of properties which allow for easy indexing/searching based on the local endpoint, remote party ID, time of recording etc.

{
  "type": "recording",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371",
  "created" : "2014-03-10T13:37:00.000+0000",
  "direction": "IN",
  "partyId": "106",
  "started": "2014-05-14T15:41:25.000+0000",
  "size": 9615,
  "callId": "ast01-1400082083.1542464",
  "linkedId": "ast01-1400082083.1542464",
  "endpoint": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535"
}
Type: recording
Property Description
type
required
The resource type ("recording").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
direction
read-only
Direction of the call.
Enum: IN, OUT
partyId
read-only
Username or phone number of the recorded party.
String
started
read-only
The time that the recorded call began (ISO8601 format).
String
size
read-only
Size of the underlying file in bytes.
Integer
callId
read-only
A unique ID for each leg of the call.
String
linkedId
read-only
The unique ID of the call itself. This ID is the same across all legs of a single call and can be used to link multiple legs of a call together.
String
endpoint
read-only
URI to the endpoint that was recording the call. If the call was internal only the outbound endpoint URI will be returned
String
List recordings

GET /customers/{customerId}/recordings

Returns a list of recordings, optionally filtered by the following query parameters:

Query String Parameters Type Description
createdAfter String Include only recordings created after the specified date/time.
createdBefore String Include only recordings created before the specified date/time.
startedAfter String Include only recordings which started after the specified date/time.
startedBefore String Include only recordings which started before the specified date/time.
callId String Include only recordings relating to a specific call leg.
linkedId String Include only recordings relating to calls with the same linked ID.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=1
HTTP/1.1 200 OK

{
  "totalItems" : 5788,
  "pageSize" : 2,
  "page" : 1,
  "items" : [ 
    {
      "type" : "recording",
      "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358372",
      "created" : "2014-03-10T14:09:00.0000+0000",
      "direction" : "OUT",
      "partyId" : "07557000000",
      "started" : "2014-03-10T14:07:00.0000+0000",
      "size" : 97365,
      "callId" : "ast01-1401721105.2847099",
      "linkedId" : "ast01-1401721105.2847099",
      "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/1928"
    }, {
      "type" : "recording",
      "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371",
      "created" : "2014-03-10T13:42:00.0000+0000",
      "direction" : "IN",
      "partyId" : "07557000000",
      "started" : "2014-03-10T13:37:00.0000+0000",
      "size" : 9615,
      "callId" : "ast01-1400082083.1542464",
      "linkedId" : "ast01-1400082083.1542464",
      "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535"
    } ],
  "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/recordings?pageSize=2&page=2"
}
Get recording

GET /customers/{customerId}/recordings/{recordingId}

Fetches the instance of a specific recording.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371
HTTP/1.1 200 OK

{
  "type": "recording",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/recordings/1358371",
  "created" : "2014-03-10T13:42:00.0000+0000",
  "direction" : "IN",
  "partyId" : "07557000000",
  "started" : "2014-03-10T13:37:00.0000+0000",
  "size" : 9615,
  "callId" : "ast01-1400082083.1542464",
  "linkedId" : "ast01-1400082083.1542464",
  "endpoint" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/2535"
}

It is also possible to fetch a copy of the audio file itself, by including the Accept header:

Accept: audio/wav

See Response Formats for more information.

Time Intervals

Resource Information
Location /customers/{customerId}/timeintervals
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) timeinterval
Additional Formats None

A time interval (timeinterval) defines the single or set of time periods which together, constitute a recurring weekly/yearly event or work pattern - for example, "Out of Hours", "Public Holidays" or "My Cat's Birthday". Time intervals are used for matching against when defining time-based routing or access rules elsewhere on the system.

{
  "type": "timeinterval",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431",
  "created" : "2014-03-10T13:37:00.000+0000",
  "name": "Lunchtimes",
  "repeat": "WEEKLY",
  "includedTimes" : [ {
    "dayOfWeek" : "MON",
    "startTime" : "12:30",
    "endTime" : "13:29"
  }, {
    "dayOfWeek" : "TUE",
    "startTime" : "12:30",
    "endTime" : "13:29"
  }, {
    "dayOfWeek" : "WED",
    "startTime" : "12:30",
    "endTime" : "13:29"
  }, {
    "dayOfWeek" : "THU",
    "startTime" : "12:30",
    "endTime" : "13:29"
  }, {
    "dayOfWeek" : "FRI",
    "startTime" : "12:15",
    "endTime" : "13:14"
  } ]
}
Type: timeinterval
Property Description
type
required
The resource type ("timeinterval").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
name
required
Name assigned to the time interval.
String
repeat
required
The repeat frequency.
Enum: WEEKLY, YEARLY
includedTimes[]
required
The times included in this event or work pattern. Each item defines an inclusive block of time on a single day of the week or year, depending on the repeat frequency. Include as many items as required to define the entire pattern or set of events.
Array
includedTimes[].dayOfWeek
conditionally required
Day of the week on which this block applies. Only valid when repeat = WEEKLY.
Enum: MON, TUE, WED, THU, FRI, SAT, SUN
includedTimes[].month
conditionally required
Used in conjunction with "dayOfMonth", defines the day of the year on which this block applies. Only valid when repeat = YEARLY.
Enum: JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC
includedTimes[].dayOfMonth
conditionally required
Used in conjunction with "month", defines the day of the year on which this block applies. Only valid when repeat = YEARLY.
Integer
includedTimes[].startTime
required
Inclusive start time (hh:mm format).
String
includedTimes[].endTime
required
Inclusive end time (hh:mm format).
String
List time intervals

GET /customers/{customerId}/timeintervals

Returns a list of previously defined time intervals on an account.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=1
HTTP/1.1 200 OK

{
  "totalItems" : 5,
  "pageSize" : 2,
  "page" : 1,
  "items" : [ {
    "type" : "timeinterval",
    "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/32",
    "created" : "2014-03-10T13:37:00.000+0000",
    "name" : "Christmas Day",
    "repeat" : "YEARLY",
    "includedTimes" : [ {
      "month" : "DEC",
      "dayOfMonth" : 25,
      "startTime" : "00:00",
      "endTime" : "23:59"
    } ]
  }, {
    "type" : "timeinterval",
    "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/31",
    "created" : "2014-03-10T13:27:00.000+0000",
    "name" : "Office Hours",
    "repeat" : "WEEKLY",
    "includedTimes" : [ {
      "dayOfWeek" : "MON",
      "startTime" : "09:00",
      "endTime" : "17:29"
    }, {
      "dayOfWeek" : "TUE",
      "startTime" : "09:00",
      "endTime" : "17:29"
    }, {
      "dayOfWeek" : "WED",
      "startTime" : "09:00",
      "endTime" : "17:29"
    }, {
      "dayOfWeek" : "THU",
      "startTime" : "09:00",
      "endTime" : "17:29"
    }, {
      "dayOfWeek" : "FRI",
      "startTime" : "09:00",
      "endTime" : "16:59"
    } ]
  } ],
  "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals?pageSize=2&page=2"
}
Get time interval

GET /customers/{customerId}/timeintervals/{timeIntervalId}

Returns the instance of a specific time interval.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431
HTTP/1.1 200 OK

{
  "type": "timeinterval",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/431",
  "created" : "2014-03-10T13:37:00.000+0000",
  "name": "Lunchtimes",
  "repeat": "WEEKLY",
  "includedTimes" : [ {
    "dayOfWeek" : "MON",
    "startTime" : "12:30",
    "endTime" : "13:29"
  }, {
    "dayOfWeek" : "TUE",
    "startTime" : "12:30",
    "endTime" : "13:29"
  }, {
    "dayOfWeek" : "WED",
    "startTime" : "12:30",
    "endTime" : "13:29"
  }, {
    "dayOfWeek" : "THU",
    "startTime" : "12:30",
    "endTime" : "13:29"
  }, {
    "dayOfWeek" : "FRI",
    "startTime" : "12:15",
    "endTime" : "13:14"
  } ]
}

Endpoints

Resource Information
Location /customers/{customerId}/endpoints
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) phone
virtual
group
queue
ivr
mailbox
Additional Formats None

Endpoints represent the internal destinations to which calls can be routed. Some endpoints are also able to initiate calls. An endpoint is itself an abstract type - each concrete sub-type, listed below, inherits a set of properties common to all endpoints (such as "name" and "shortNumber"), whilst adding its own properties according to its functionality.

Important: once an endpoint of a particular type has been created, its type cannot be changed.

Endpoint Types
Phone Extension

For connecting a SIP handset, softphone or mobile app and to enable direct inbound/outbound calls over the Internet. Typically, each member of the team will have their own extension, but multiple devices may be connected to a single extension. Each phone extension includes an associated voicemail user and SIP identity and supports features such as call recording, call forwarding and call waiting. It can also be a member of one or more ring groups and/or call queues. Note: call charges apply to forwarded calls.

Virtual Extension

Used for linking an existing mobile or landline number to the system as if it were a regular extension, with its own 3-digit number for receiving incoming calls. A virtual extension can be a member of a group/queue in exactly the same way as a regular phone extension, but does not include any of the additional features (voicemail, recording etc). Note: call charges apply to forwarded calls.

Ring Group

Calls directed to a ring group will be forked to multiple phone/virtual extensions either in parallel, or cascaded from one to another in series. If one or more phones are busy the others will still ring.

Call Queue

On entry, callers may be greeted with a welcome message, then played music (or a custom marketing message) until their call is answered. Options include setting the ring strategy, maximum wait time and failover destination for calls exceeding this limit.

IVR (Auto-Attendant)

Direct callers to the most appropriate person or department by giving them a number of options - e.g. "Press 1 for support, 2 for accounts" - or allow callers to reach individual extensions directly if they know the number.

Additional Mailbox

Although every phone extension has its own mailbox, sometimes additional mailboxes are required for things like out-of-hours messages or recorded information lines. Messages may be delivered via email or retrieved from any connected handset on the system, in the same way as any other mailbox.

The properties of each endpoint type are listed below.

Type: phone
Property Description
type
required
The resource type ("phone").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
shortNumber
required
The 3-digit internal number of this endpoint.
String
name
required
Name assigned to the endpoint.
String
email
optional
Email address for notifications (e.g. voicemail).
String
timeout
required
The time in seconds after which incoming calls should be considered unanswered (default 30).
Integer
callWaiting
required
Whether or not call waiting is enabled (default true).
Boolean
callRecording
required
Whether calls should be recorded for this extension and when (default OFF).
Enum: ALWAYS, OFF, ON_DEMAND
voicemailEnabled
required
Whether or not voicemail is enabled for this extension (default false).
Boolean
links[]
read-only
A collection of links to related sub-resources.
Array
Type: virtual
Property Description
type
required
The resource type ("virtual").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
shortNumber
required
The 3-digit internal number of this endpoint.
String
name
required
Name assigned to the endpoint.
String
destination
required
External number to which calls should be forwarded.
String
timeout
required
The time in seconds after which calls should be considered unanswered (default 30).
Integer
screeningEnabled
required
Whether or not call screening is enabled (default false).
Boolean
Type: group
Property Description
type
required
The resource type ("group").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
shortNumber
required
The 3-digit internal number of this endpoint.
String
name
required
Name assigned to the endpoint.
String
memberTimeout
required
How long in seconds to try each member of the group (default 30).
Integer
cascadeDelay
required
Delay in seconds before trying the next member of the group (default 0). A zero delay denotes a ring-all strategy (ring all members simultaneously). An overlap between members can be achieved by setting the delay greater than zero but less than "memberTimeout".
Integer
failoverDestination
optional
URI of another endpoint to which calls should be forwarded on eventual timeout or failure.
String
Type: queue
Property Description
type
required
The resource type ("queue").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
shortNumber
required
The 3-digit internal number of this endpoint.
String
name
required
Name assigned to the endpoint.
String
maxWait
required
The maximum amount of time in seconds a caller can wait in the queue (default 600).
Integer
Type: ivr
Property Description
type
required
The resource type ("ivr").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
shortNumber
required
The 3-digit internal number of this endpoint.
String
name
required
Name assigned to the endpoint.
String
timeout
required
The number of seconds to wait for a keypress after the initial message has been played (default 5).
Integer
Type: mailbox
Property Description
type
required
The resource type ("mailbox").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
shortNumber
required
The 3-digit internal number of this endpoint.
String
name
required
Name assigned to the endpoint.
String
email
required
Email address to which we should send new messages.
String
links[]
read-only
A collection of links to related sub-resources.
Array
List endpoints

GET /customers/{customerId}/endpoints

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=2&page=1
HTTP/1.1 200 OK

{
  "totalItems": 25,
  "pageSize": 2,
  "page": 1,
  "items":  [
     {
      "type": "ivr",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102",
      "created" : "2014-03-10T13:38:00.000+0000",
      "shortNumber": "001",
      "name": "Main IVR",
      "timeout": 4
    },
    {
      "type": "phone",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101",
      "created" : "2014-03-10T13:37:00.000+0000",
      "shortNumber" : "102",
      "name" : "John Simmonds",
      "email" : "john@sipcentric.com",
      "timeout" : 30,
      "callWaiting" : true,
      "callRecording" : "ALWAYS",
      "voicemailEnabled" : true
    }
  ],
  "nextPage": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints?pageSize=1&page=2"
}
Get endpoint

GET /customers/{customerId}/endpoints/{endpointID}

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101
HTTP/1.1 200 OK

{
  "type": "phone",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101",
  "created" : "2014-03-10T13:37:00.000+0000",
  "shortNumber" : "102",
  "name" : "John Simmonds",
  "email" : "john@sipcentric.com",
  "timeout" : 30,
  "callWaiting" : true,
  "callRecording" : "ALWAYS",
  "voicemailEnabled" : true,
  "links" : {
    "sip" : "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/sip",
    "voicemail" : "http://pbx.sipcentric.com/api/v1/customers/25/endpoints/101/voicemail"
  }  
}

Phone Numbers

Resource Information
Location /customers/{customerId}/phonenumbers
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) did
Additional Formats None

Phone numbers provide a route into the system from outside - they can support calls and optionally SMS messages, where available. Each inbound number is represented by a did.

{
  "type" : "did",
  "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50",
  "created" : "2014-03-10T13:37:00.000+0000",
  "number" : "01212854400",
  "identifier" : "",
  "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101",
  "smsEnabled" : true,
  "smsAllowIncoming" : true,
  "smsNotificationEmail" : "support@sipcentric.com",
  "smsNotificationUrl" : "https://example.com/sms",
  "faxEnabled" : false,
  "routingRules" : [ {
    "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594",
    "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102"
  }, {
    "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625",
    "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102"
  }, {
    "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704",
    "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102"
  } ]
}
Type: did
Property Description
type
required
The resource type ("did").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
number
read-only
The phone number in E.164 format.
String
identifier
optional
An optional label which is prefixed to the caller ID name on incoming calls to identify which number was called. Useful when multiple numbers each route to the same internal endpoint.
String
destination
optional
The URI of the internal endpoint to which calls to this number will be routed by default. Valid only if faxEnabled = false.
String
smsEnabled
read-only
Determines whether SMS functionality is supported on this number. Only certain numbers will have SMS capabilities. It is not possible to receive SMS messages on ported numbers.
Boolean
smsAllowIncoming
conditionally required
A user may choose whether to allow or disallow incoming messages. Valid only if smsEnabled = true.
Boolean
smsNotificationEmail
optional
The email address to which we should send incoming SMS notifications. Valid only if smsEnabled = true.
String
smsNotificationUrl
optional
When an SMS is received to this number, we will send a POST to the specified URL and include the following form encoded parameters: "to", "from", "body", "udh" (user data header - used for linking concatenated messages together). Valid only if smsEnabled = true.
String
faxEnabled
required
Whether this number should be designated for fax-to-email. It is not currently possible to receive both voice calls and faxes to a single number - therefore, "faxEnabled" and "destination" are mutually exclusive.
Boolean
faxNotificationEmail
optional
The email address to which we should send incoming faxes (converted to PDF). Valid only if faxEnabled = true.
routingRules[]
optional
Time-based routing rules (exceptions) that apply to this number.
Array
routingRules[].timeInterval
required
URI of the time interval during which this rule applies.
String
routingRules[].destination
required
URI of endpoint to which calls during the matched time interval should routed.
String
List phone numbers

GET /customers/{customerId}/phonenumbers

Returns a list of all phone numbers on a customer account.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=1
HTTP/1.1 200 OK

{
  "totalItems" : 15,
  "pageSize" : 2,
  "page" : 1,
  "items" : [ {
    "type" : "did",
    "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47",
    "created" : "2014-03-10T13:37:00.000+0000",
    "number" : "01212854400",
    "identifier" : "Main",
    "smsEnabled" : true,
    "smsAllowIncoming" : true,
    "smsNotificationEmail" : "contact@fredbloggs.com",
    "smsNotificationUrl" : "https://example.com/sms",
    "faxEnabled" : false
  }, {
    "type" : "did",
    "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/50",
    "created" : "2014-03-10T13:37:00.000+0000",
    "number" : "01212854411",
    "identifier" : "",
    "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/101",
    "smsEnabled" : true,
    "smsAllowIncoming" : true,
    "smsNotificationEmail" : "support@sipcentric.com",
    "smsNotificationUrl" : "https://example.com/sms",
    "faxEnabled" : false,
    "routingRules" : [ {
      "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/594",
      "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102"
    }, {
      "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/625",
      "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102"
    }, {
      "timeInterval" : "https://pbx.sipcentric.com/api/v1/customers/25/timeintervals/704",
      "destination" : "https://pbx.sipcentric.com/api/v1/customers/25/endpoints/102"
    } ]
  } ],
  "nextPage" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers?pageSize=2&page=2"
}
Get phone number

GET /customers/{customerId}/phonenumbers/{numberId}

Retrieves the instance of a specific phone number.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47
HTTP/1.1 200 OK

{
  "type" : "did",
  "uri" : "https://pbx.sipcentric.com/api/v1/customers/25/phonenumbers/47",
  "created" : "2014-03-10T13:37:00.000+0000",
  "number" : "01212854400",
  "identifier" : "Main",
  "smsEnabled" : true,
  "smsAllowIncoming" : true,
  "smsNotificationEmail" : "contact@fredbloggs.com",
  "smsNotificationUrl" : "https://example.com/sms",
  "faxEnabled" : false
}

Outgoing Caller IDs

Resource Information
Location /customers/{customerId}/outgoingcallerids
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) outgoingcallerid
Additional Formats None

Usually, when making calls or sending SMS messages from an account, the outgoing ID should be set to one of the phone numbers on that account. It is possible, however, to use a name (in the case of SMS) or a number which is hosted elsewhere, as long as ownership can be verified. Once a custom caller ID has been requested and approved by us it will appear here, represented by an outgoingcallerid.

{
  "type": "outgoingcallerid",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114",
  "created" : "2014-03-10T13:37:00.000+0000",
  "number": "07932000000",
  "allowCalls": false,
  "allowSms": true
}
Type: outgoingcallerid
Property Description
type
required
The resource type ("outgoingcallerid").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
number
read-only
Name or number to be displayed for outgoing calls and/or messages.
String
allowCalls
read-only
Whether the name/number has been approved for use with outgoing calls.
Boolean
allowSms
read-only
Whether the name/number has been approved for use with outgoing SMS.
Boolean
List outgoing caller ids

GET /customers/{customerId}/outgoingcallerids

Lists the IDs which have been approved for use on the account.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids
HTTP/1.1 200 OK

{
  "totalItems": 2,
  "pageSize": 20,
  "page": 1,
  "items":  [
    {
      "type": "outgoingcallerid",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/115",
      "created" : "2014-03-10T13:37:00.000+0000",
      "number": "Sipcentric",
      "allowCalls": false,
      "allowSms": true
    },
    {
      "type": "outgoingcallerid",
      "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114",
      "created" : "2014-03-10T13:37:00.000+0000",
      "number": "01212854411",
      "allowCalls": true,
      "allowSms": true
    }
  ]
}
Get outgoing caller id

GET /customers/{customerId}/outgoingcallerids/{id}

Get the instance of a specific caller ID.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114
HTTP/1.1 200 OK

{
  "type": "outgoingcallerid",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/outgoingcallerids/114",
  "created" : "2014-03-10T13:37:00.000+0000",
  "number": "01212854411",
  "allowCalls": true,
  "allowSms": true
}

Credit Status

Resource Information
Location /customers/{customerId}/creditstatus
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) creditstatus
Additional Formats None

The credit status sub-resource returns the current call credit status of an account, represented by a creditstatus instance.

{
  "type": "creditstatus",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus",
  "accountType": "PREPAID",
  "creditRemaining": 19.571
}
Type: creditstatus
Property Description
type
read-only
The resource type ("creditstatus")
String
uri
read-only
URI of this instance.
String
accountType
read-only
The type of account.
Enum: PREPAID, POSTPAID
balance
read-only
Balance on the account
Float
Get credit status

GET /customers/{customerId}/creditstatus

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/creditstatus
HTTP/1.1 200 OK

{
  "type": "creditstatus",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/creditstatus",
  "accountType": "PREPAID",
  "balance": 19.571
}

Call Bundles

Resource Information
Location /customers/{customerId}/callbundles
Rate Limited? Yes
Requests per rate limit window 1200/hour
Authentication Basic Auth
HTTP Method(s) GET
JSON Representation(s) customerbundle
Additional Formats None

The call bundles sub-resource contains all bundles which have been added to an account - each is represented by a customerbundle and includes the current status, as well as used and remaining minutes.

    {
      type: "customerbundle",
      uri: "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040",
      created: "2014-03-01T00:00:00.000+0000",
      name: "1000 Mins - UK Local/National",
      inclusiveMins: 1000,
      priceMonthly: 5,
      validFrom: "2014-03-01T00:00:00.000+0000",
      validTo: "2014-03-31T23:59:59.999+0000",
      usedMins: 57,
      availableMins: 943,
      autoRenew: true,
      status: "ACTIVE"
    }
Type: customerbundle
Property Description
type
required
The resource type ("customerbundle").
String
uri
read-only
URI of this instance.
String
created
read-only
UTC time when the resource was created (ISO8601 format).
String
name
read-only
The bundle name.
String
inclusiveMins
read-only
The number of minutes to predefined destinations included in the bundle.
Integer
priceMonthly
read-only
The monthly renewal cost in GBP.
Integer
validFrom
read-only
UTC time from which the bundle is valid (ISO8601 format).
String
validTo
read-only
UTC time when the bundle expires (ISO8601 format).
String
usedMins
read-only
The number of minutes used up.
Integer
availableMins
read-only
The number of minutes remaining.
Integer
autoRenew
required
Whether the bundle is set to automatically renew.
Boolean
status
read-only
The current status of the bundle.
Enum: ACTIVE, EXPIRED
List call bundles

GET /customers/{customerId}/callbundles

List all bundles added to an account.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles
HTTP/1.1 200 OK

{
  "totalItems": 1,
  "pageSize": 20,
  "page": 1,
  "items":  [
     {
      type: "customerbundle",
      uri: "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040",
      created: "2014-03-01T00:00:00.000+0000",
      name: "1000 Mins - UK Local/National",
      inclusiveMins: 1000,
      priceMonthly: 5,
      validFrom: "2014-03-01T00:00:00.000+0000",
      validTo: "2014-03-31T23:59:59.999+0000",
      usedMins: 57,
      availableMins: 943,
      autoRenew: true,
      status: "ACTIVE"
    }
  ]
}
Get call bundle

GET /customers/{customerId}/callbundles/{bundleId}

Fetches the instance of a specific customer bundle.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040
HTTP/1.1 200 OK

{
  "type": "customerbundle",
  "uri": "https://pbx.sipcentric.com/api/v1/customers/25/callbundles/1040",
  "created": "2014-03-01T00:00:00.000+0000",
  "name": "1000 Mins - Local/National (Free)",
  "inclusiveMins": 1000,
  "priceMonthly": 5,
  "validFrom": "2014-03-01T00:00:00.000+0000",
  "validTo": "2014-03-31T23:59:59.999+0000",
  "usedMins": 57,
  "availableMins": 943,
  "autoRenew": true,
  "status": "ACTIVE"
}

Global Resources

Token Generator

In some situations it's not possible to use basic authentication in a GET request, such as downloading a call recording in a client's browser.

To solve this issue we have added a token generator for pre-authenticating these requests. This will return a single-use token for accessing any readonly resources you would normally have to authenticate for.

Get token
GET https://pbx.sipcentric.com/api/v1/tokengenerator

{
  "type": "authtoken",
  "id": "318f9a6d-162e-4d46-89d2-3d7cb2f4db16",
  "created": "2014-07-11T15:11:12.477+0000",
  "expires": "2014-07-11T16:11:12.477+0000"
}

You can now use this token to get a call recording using the tokenid parameter in the GET request:

https://pbx.sipcentric.com/api/v1/customers/25/recordings/242348.wav?tokenid=318f9a6d-162e-4d46-89d2-3d7cb2f4db16

Anyone that tried to use the request again will get a 401 Unauthorized. This prevents replay attacks from getting any data.

Stream

GET https://pbx.sipcentric.com/api/v1/stream

You can create a standing HTTP connection to our API for live streaming events. This means you can process events in near real time, without having to poll other resources and potentially avoid hitting request limits. Data is returned as JSON objects.

Currently the following is available via the streaming API:

Example object:

{
  "event": "incomingcall",
  "location": null,
  "values": {
    "callerIdNumber": "01234567890",
    "callerIdName": "Support",
    "endpoint": "/customers/325/endpoints/6874"
  }
}
Connecting

To work with the streaming API you will need to create an indefinite HTTP GET request and process the data as it is received. Our API will hold the connection open as long as possible. But if the connection does disconnect due to network / client issues you should handle this by reconnecting as soon as possible. We also send a heartbeat object every 60 seconds which helps keep the connection open and you can also check for this object and reconnect if it isn't received within a suitable time period.

The streaming API requires you to authenticate with Basic Authentication. The stream data you receive depends on the user you authenticate with.

The best way to work with the Stream in JavaScript/Node.js is to use the Atmosphere client which establishes the connection and handles disconnects automatically.

Most HTTP client libraries let you handle the connection as a stream. Which allows you to process the data as it is received.

Responses

All of the event objects are in a standard format:

{
  "event": ...,
  "location": ...,
  "values":{ ... }
}

Current events that can be consumed:

Event values:

Type: incomingcall
Property Description
callerIdNumber The callers number.
String
callerIdName Caller ID
String
endpoint URI of the endpoint.
String
Type: smsreceived
Property Description
to The public number the SMS was delivered to.
String
from The number the SMS was received from
String
excerpt Summary of message.
String
Type: smsdelivered
Property Description
None No values are returned for this object.