Version 1

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:

X-RateLimit-Limit: the number of requests allowed per 60 minute window
X-RateLimit-Remaining: the number of requests left for the 60 minute window
X-RateLimit-Reset: the number of seconds before next reset

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:

Extension User
Company Admin
Reseller

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",
  "country": "GB",
  "properties": {
        "testid" : "abc123",
    "test2" : "GB134324"
  },
  "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
accountType read-only	The account types are: Business (business) - full hosted PBX with all the usual business features (call queues, IVRs etc) Residential Plus (residential) - a cut down version aimed at home users, but still having the concept of extensions and ring groups to enable everyone in the home to have their own extension/number and use the mobile app etc. Residential (wlr) - a basic PSTN replacement service, having just a phone number and voicemail. No concept of extensions or mobile apps.
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
country required	Primary location country. String
properties[] optional	A collection of customisable properties that could be used to store varying ids Array
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:

Local - between two endpoints on the same account.
Domain - between two accounts on the Sipcentric network.
External - to/from an external number on the PSTN.

{
  "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.
endpointId	Integer	Only include calls involving a specific endpoint ID.

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.

Phone Status (Do Not Disturb)

GET /customers/{customerId}/endpoints/{endpointId}/phonestatus

To check the current status of an endpoint, run the above - dndActive is a boolean that will confirm whether the endpoint is happy to accept calls. NB: Regardless of how many devices are connected to an endpoint, if Do Not Disturb (dnd) is set, then no calls will be presented to the endpoint.

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus

{
    "type": "phonestatus",
    "id": "94",
    "uri": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus",
    "parent": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94",
    "dndActive": false
}

PUT /customers/{customerId}/endpoints/{endpointId}/phonestatus

To change the current status of an endpoint, please use a PUT as per the below.

Example request:

PUT  https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus

{
    "type": "phonestatus",
    "dndActive": true
}

HTTP/1.1 200 OK

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
entrySound required	The URL of the sound to play on entry. String
items[] required	The items in this IVR menu, i.e. the keys the user can press and the corresponding actions to perform. Array
items[].key required	The key the user can press. String
items[].action required	The action to perform. Object
items[].action.type required	The type of action to perform. transfer - transfers the caller to an endpoint of type "phone" or "virtual", optionally playing a sound first playsound - plays a sound and hangs up goto - transfers the caller to another endpoint of type "ivr" dialext - prompts the user for an extension and then transfers the caller to that number Enum: transfer, playsound, goto, dialext
items[].action.destination required	The URL of the endpoint to transfer to. Note that the type of the endpoint must match the type of the action - "transfer" transfers to "phone" or "virtual" endpoints and "goto" tranfers to "ivr" endpoints. Only valid when type = transfer or type = goto. String
items[].action.playSound optional	The URL of the sound to play before transferring. Only valid when type = transfer. String
items[].action.display optional	A string to prepend to the caller ID when transferring. Only valid when type = transfer. String
items[].action.sound required	The URL of the sound to play before hanging up. Only valid when type = playsound. 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 Status

GET /customers/{customerId}/endpoints/{endpointId}/phonestatus

Example request:

GET https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus

{
    "type": "phonestatus",
    "id": "94",
    "uri": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus",
    "parent": "https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94",
    "dndActive": false
}

PUT /customers/{customerId}/endpoints/{endpointId}/phonestatus

To change the current status of an endpoint, please use a PUT as per the below.ss

Example request:

PUT  https://pbx.sipcentric.com/api/v1/customers/5/endpoints/94/phonestatus

{
    "type": "phonestatus",
    "dndActive": true
}

HTTP/1.1 200 OK

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:

Incoming call notifications
Incoming SMS messages
SMS delivery receipts

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:

incomingcall
smsreceived
smsdelivered

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.

Overview​

Base URL​

Limits​

HTTP Methods​

GET​

Response Codes​

POST​

Response Codes​

PUT​

Response Codes​

DELETE​

Response Codes​

Method Overloading​

Authentication​

Response Formats​

List Resources​

Pagination​

Query Parameters​

Data Formats​

Dates & Times​

Customer Resources​

Customers​

List customers​

Get customer​

Phone Book​

List phone book entries​

Read phone book entry​

Create phone book entry​

Update phone book entry​

Delete phone book entry​

SMS​

List SMS messages​

Get SMS Message​

Send SMS​

Calls​

Get call history​

Originate call​

Phone Status (Do Not Disturb)​

Sounds​

Sound Types​

Prompt​

Music​

List sounds​

Get sound​

Recordings​

List recordings​

Get recording​

Time Intervals​

List time intervals​

Get time interval​

Endpoints​

Endpoint Types​

Phone Extension​

Virtual Extension​

Ring Group​

Call Queue​

IVR (Auto-Attendant)​

Additional Mailbox​

List endpoints​

Get endpoint​

Phone Status​

Phone Numbers​

List phone numbers​

Get phone number​

Outgoing Caller IDs​

List outgoing caller ids​

Get outgoing caller id​

Credit Status​

Get credit status​

Call Bundles​

List call bundles​

Get call bundle​

Global Resources​

Token Generator​

Get token​

Stream​

Connecting​

Responses​

Overview

Base URL

Limits

HTTP Methods

GET

Response Codes

POST

Response Codes

PUT

Response Codes

DELETE

Response Codes

Method Overloading

Authentication

Response Formats

List Resources

Pagination

Query Parameters

Data Formats

Dates & Times

Customer Resources

Customers

List customers

Get customer

Phone Book

List phone book entries

Read phone book entry

Create phone book entry

Update phone book entry

Delete phone book entry

SMS

List SMS messages

Get SMS Message

Send SMS

Calls

Get call history

Originate call

Phone Status (Do Not Disturb)

Sounds

Sound Types

Prompt

Music

List sounds

Get sound

Recordings

List recordings

Get recording

Time Intervals

List time intervals

Get time interval

Endpoints

Endpoint Types

Phone Extension

Virtual Extension

Ring Group

Call Queue

IVR (Auto-Attendant)

Additional Mailbox

List endpoints

Get endpoint

Phone Status

Phone Numbers

List phone numbers

Get phone number

Outgoing Caller IDs

List outgoing caller ids

Get outgoing caller id

Credit Status

Get credit status

Call Bundles

List call bundles

Get call bundle

Global Resources

Token Generator

Get token

Stream

Connecting

Responses