api_documentation

SureVoIP API Technical Documentation

Introduction

Welcome to the SureVoIP RESTful hypermedia API

(sometimes known as a VoIP REST API, Telecom REST API, SIP API, Hypermedia API or just VoIP API.)

The SureVoIP API is a way for you to automate your interaction with the SureVoIP platforms. With the API, you can create your own scripts, applications or mashups which can:

  • create customers
  • search numbers
  • provision numbers
  • send SMS texts
  • send faxes
  • create outbound calls
  • schedule announcements
  • schedule call hangups with an announcement
  • subscribe to events/alerts
  • track calls
  • retrieve invoices
  • grab your SIP details
  • check your IP address
  • be 100% self-sufficient
  • and much more!

Since the API is based on RESTful principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API.

All of our examples are provided using curl so you can just copy and paste them for testing. We will have a Sandbox area soon.

Note: This API is in a beta state. Breaking changes may occur, but will be very unlikely :-)

Helper Libraries

The API documentation explains the format for raw HTTP calls to the SureVoIP API. We also have helper libraries in a number of popular programming languages, which make it easy for you to get started.

Server Address

The base server address is: https://api.surevoip.co.uk/

Please note that HTTPS is required. You will not be able to connect through unencrypted HTTP.

Request Formats

You can use any of the HTTP Verbs below and send the same formats as described in the Response Formats section.

HTTP Verbs

Where possible, API v1 strives to use appropriate HTTP verbs for each action:

HEAD

Can be issued against any resource to get just the HTTP header info.

OPTIONS

Can be issued against any resource to find out which HTTP Verbs are supported: 

curl -i -X OPTIONS -u username:password https://api.surevoip.co.uk/

We will automatically respond with a 200 OK with the “Allow” header populated with the list of implemented request methods: 

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 15:40:51 GMT
Content-Type: text/plain; charset=UTF-8
Connection: keep-alive
Allow: GET
Content-Length: 54
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: no-auth
X-SureVoIP-API-Version: 3.50

GET

Used for retrieving resources.

POST

Used for creating resources, or performing custom actions (when implemented)

PUT

Used for replacing resources or collections.

DELETE

Used for deleting resources.

Response Formats

Response formats can be set via the Content-Type header (Content-Type: “application/json”) or a query param of ?content-type=application/xml if using a GET

We select the content-type based on:

The Content-Type Header

If the incoming HTTP Request has a Content-Type header set, we will use it.

The content-type Query Parameter

If this is a GET request, you can supply a content-type query parameter.

Evaluating the Accept Header

Finally, if the client provided an Accept header, we will evaluate it and use the best-ranked choice.

Supported Content-Types

We support for all resources:

Content-Type Description
text/plainPlain text format
text/xmlXML format
text/htmlBasic HTML
application/jsonJSON
application/xmlXML format
text/javascriptJSONP - If a callback=? parameter is passed, this returns javascript in the form of: $callback($serializedJSON);The usual MIME types for this serialization format are:
'text/javascript', 'application/x-javascript', 'application/javascript'.
text/x-data-dumperData::Dumper format
text/x-data-denterData::Denter format
text/x-data-taxiData::Taxi format
application/x-storableStorable format format
application/x-freezethawFreezeThaw format
text/x-config-generalConfig::General format
text/x-php-serializationPHP::Serialization format

If you'd like one added please contact surevoip-api@suretecsystems.com

Error responses

The specific responses (successful ones) are described in the documentation section for each method.

However, if something goes wrong, our standard error message follows this format (JSON in this example): 

HTTP/1.1 404 Not Found
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 16:14:30 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 2675
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "error":"Cannot find what you were looking for!"
}

If you are creating (POST) or updating (PUT) resources and there is an error with your data, we will return: 

HTTP/1.1 400 Bad Request
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 16:26:59 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 2703
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "errors":[
      {
         "message":[
            "Format is 447123123456. No + allowed"
         ],
         "field":"to"
      },
      {
         "message":[
            "Must not contain spaces",
            "Must be made up of letters, digits, and underscores"
         ],
         "field":"from"
      },
      {
         "message":[
            "Message field is required"
         ],
         "field":"message"
      }
   ]
}

gzip

Responses can be gzip-encoded on demand. This is nice if your bandwidth is limited, or if big results are causing performance issues.

To enable gzip, simply add the following header to your request: 

Accept-Encoding: gzip

Note: this is currently being tested and may not be available

Limits

The SureVoIP API has usage limits to avoid individual rampant applications degrading the overall user experience. We limit requests to 5000 per hour. This is keyed off either your login, your OAuth 2.0 token, or request IP. You can check the returned HTTP headers of any API request to see your current status:

The response headers are: 

X-SureVoIP-API-RateLimit-Limit
X-SureVoIP-API-RateLimit-Remaining
X-SureVoIP-API-RateLimit-TimeToReset
X-SureVoIP-API-RateLimit-TimeToResetSecs

An example of the values of these headers: 

X-SureVoIP-API-RateLimit-Limit: 5000
X-SureVoIP-API-RateLimit-Remaining: 4966
X-SureVoIP-API-RateLimit-TimeToReset: 55 mins 10 secs
X-SureVoIP-API-RateLimit-TimeToResetSecs: 3310

If you feel restricted by these limits, please feel free to contact SureVoIP support and request a paid for higher limit. The limits are primarily here to protect the system from poorly coded applications, not to restrict you as a user/customer.

Note: this is currently being tested and may not be present

Authentication

Authentication is needed in order to use the SureVoIP API, and for this a SureVoIP account is required.

Basic Authentication

The credentials used for accessing the API via Basic Authentication (encrypted over HTTPS) are the same used to access the SureVoIP control panel - in other words your control panel username and password. We only support HTTPS.

This type of authentication method is good for apps that are only used from one place and testing via your browser.

You will provide your credentials every time you make a request. No sessions are used.

See the Sandbox/Play area for more info.

OAuth 2.0 protocol

SureVoIP's RESTful API uses the OAuth 2.0 protocol for authentication and security. SureVoIP acts as an OAuth 2.0 provider, and all SureVoIP applications act as corresponding OAuth 2.0 consumers. All communications with SureVoIP as an OAuth 2.0 provider is via SSL, as OAuth 2.0 does not provide for token encryption.

SureVoIP provides several different authentication models for granting access to SureVoIP services. These models are discussed in more detail in the documentation sections that follow (when this work is finished and released on GitHub and the CPAN Open Source when the docs are written).

OAuth 2 Flowcharts

Getting Started

You can test the resources straight away, even with out authentication. The following resources can be used to answer these questions:

  • can I talk to the SureVoIP API at all? This is covered by support/ip-address and support/service-status
  • can I accurately send and receive data, including accounting for Unicode/decode/encode issues? This covered by support/echo
  • can I authenticate? This covered by any resource that requires authentication, for example: customers

Helpful support resources:

Code Examples

We are slowly adding various code examples to the SureVoIP API Examples GitHub repo.

Please check there from time to time.

Event notification and WebHooks

This work is currently being worked on and when finished will be released on GitHub and the CPAN Open Source). We'll send out an email and blog post when ready.

RESTful Resources

The following sections describe in detail the resources available, what you can send, what formats you can expect to receive from the SureVoIP API all using the uniform HTTP interface. There are also examples you can copy and paste for use with curl.

For a complete list of resources and response codes etc. please see the Response Codes table.

By default you will see hypermedia that shows you what the available top level resources are, therefore running: 

curl -i https://api.surevoip.co.uk/ -H 'Content-Type: application/json'

returns: 

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 16:43:11 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 656
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Version: 3.50

{
   "resources":{
      "calls":"https://api.surevoip.co.uk/calls",
      "sms":"https://api.surevoip.co.uk/sms",
      "numbers":"https://api.surevoip.co.uk/numbers",
      "contact":"https://api.surevoip.co.uk/contact",
      "sip":"https://api.surevoip.co.uk/sip",
      "partners":"https://api.surevoip.co.uk/partners",
      "faxes":"https://api.surevoip.co.uk/faxes",
      "areacodes":"https://api.surevoip.co.uk/numbers/areacodes",
      "service-status":"https://api.surevoip.co.uk/support/service-status",
      "porting":"https://api.surevoip.co.uk/porting",
      "customers":"https://api.surevoip.co.uk/customers",
      "ip-address":"https://api.surevoip.co.uk/support/ip-address",
      "echo":"https://api.surevoip.co.uk/support/echo",
      "billing":"https://api.surevoip.co.uk/billing"
   }
}

List resources

All list resources support:

The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive and we also support Conditional GET and dates are in strptime format:

Parameter Description
pagewhich page you'd like
offsetWhere to start from
limitGive me only this amount of results

The following hypermedia will also be present: 

{
   "resources":{
      "calls":"https://api.surevoip.co.uk/calls",
      "sms":"https://api.surevoip.co.uk/sms",
      "numbers":"https://api.surevoip.co.uk/numbers",
      "contact":"https://api.surevoip.co.uk/contact",
      "sip":"https://api.surevoip.co.uk/sip",
      "partners":"https://api.surevoip.co.uk/partners",
      "faxes":"https://api.surevoip.co.uk/faxes",
      "areacodes":"https://api.surevoip.co.uk/numbers/areacodes",
      "service-status":"https://api.surevoip.co.uk/support/service-status",
      "porting":"https://api.surevoip.co.uk/porting",
      "customers":"https://api.surevoip.co.uk/customers",
      "ip-address":"https://api.surevoip.co.uk/support/ip-address",
      "billing":"https://api.surevoip.co.uk/billing"
   },
   "entries_per_page":50,
   "last_page":239,
   "current_page":1,
   "page_links":[
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=1&limit=50&offset=0",
         "title":"first_page"
      },
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=1&limit=50&offset=0",
         "title":"previous_page"
      },
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=1&limit=50&offset=0",
         "title":"current_page"
      },
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=2&limit=50&offset=0",
         "title":"next_page"
      },
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=239&limit=50&offset=0",
         "title":"last_page"
      }
   ],
   "next_page":2,
   "previous_page":null,
   "total_entries":"11941",
   "first_page":1,
   "limit":50,
   "offset":0,
   "list":[
      {
         ....
      },
      {
         ....
      },
      {
         ....
      }
   ]
}

Partners

Partner resources are the same as customer resources, but live at: 

https://api.surevoip.co.uk/partners/{partner_name}/customers/{customer_name}/calls

etc.

Partners can provision their own customers, customer numbers, allocate them and various other things.

Customers

Your account

Your own customer account can be accessed by authenticating as a direct customer to the top level customer resource: 

curl -i -X GET -u username:password https://api.surevoip.co.uk/customers

This would return a Location header, 302 Found and a link to your account: 

HTTP/1.1 302 Found
Server: nginx/1.0.14
Date: Fri, 18 Jan 2017 10:42:03 GMT
Content-Type: application/json
Connection: keep-alive
Location: https://api.surevoip.co.uk/customers/{account}
Vary: Content-Type
Content-Length: 2802
X-Catalyst: 5.90011
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "resources":{
      "calls":"https://api.surevoip.co.uk/calls",
      "sms":"https://api.surevoip.co.uk/sms",
      "numbers":"https://api.surevoip.co.uk/numbers",
      "contact":"https://api.surevoip.co.uk/contact",
      "sip":"https://api.surevoip.co.uk/sip",
      "partners":"https://api.surevoip.co.uk/partners",
      "faxes":"https://api.surevoip.co.uk/faxes",
      "areacodes":"https://api.surevoip.co.uk/numbers/areacodes",
      "service-status":"https://api.surevoip.co.uk/support/service-status",
      "porting":"https://api.surevoip.co.uk/porting",
      "customers":"https://api.surevoip.co.uk/customers",
      "ip-address":"https://api.surevoip.co.uk/support/ip-address",
      "echo":"https://api.surevoip.co.uk/support/echo",
      "billing":"https://api.surevoip.co.uk/billing"
   },
   "location":"https://api.surevoip.co.uk/customers/{account}",
   "customer_resources":{
      "urls":[
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/calls",
            "title":"calls"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/calls/stats",
            "title":"call stats"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/billing/invoices",
            "title":"billing invoices"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/billing/contact",
            "title":"billing contact details"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/999-address",
            "title":"999 address"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/support/",
            "title":"support tickets"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers",
            "title":"numbers"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/countries/",
            "title":"numbers by country"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/states/",
            "title":"numbers by states"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/cities/",
            "title":"numbers by city"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/areacodes/",
            "title":"numbers by areacode"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/faxes",
            "title":"faxes"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/sms",
            "title":"sms"
         },
         {
            "href":"https://api.surevoip.co.uk/contact",
            "title":"contact"
         },
         {
            "href":"https://api.surevoip.co.uk/support/ip-address",
            "title":"ip-address"
         },
         {
            "href":"https://api.surevoip.co.uk/support/echo",
            "title":"echo"
         },
         {
            "href":"https://api.surevoip.co.uk/support",
            "title":"numbers"
         },
         {
            "href":"https://api.surevoip.co.uk/numbers/countries/",
            "title":"numbers by country"
         },
         {
            "href":"https://api.surevoip.co.uk/numbers/states/",
            "title":"numbers by states"
         },
         {
            "href":"https://api.surevoip.co.uk/numbers/cities/",
            "title":"numbers by city"
         },
         {
            "href":"https://api.surevoip.co.uk/numbers/areacodes/",
            "title":"numbers by areacode"
         },
         {
            "href":"https://api.surevoip.co.uk/support/service-status",
            "title":"service-status"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/sip",
            "title":"sip"
         }
      ]
   }
}

You can then use that Location header to GET your account details: 

curl -i -X GET -u username:password https://api.surevoip.co.uk/customers/{account}

which returns: 

HTTP/1.1 200 OK
Server: nginx/1.0.14
Date: Fri, 18 Jan 2017 10:43:25 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 3117
X-Catalyst: 5.90011
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50
  
{
   "resources":{
      "calls":"https://api.surevoip.co.uk/calls",
      "sms":"https://api.surevoip.co.uk/sms",
      "numbers":"https://api.surevoip.co.uk/numbers",
      "contact":"https://api.surevoip.co.uk/contact",
      "sip":"https://api.surevoip.co.uk/sip",
      "partners":"https://api.surevoip.co.uk/partners",
      "faxes":"https://api.surevoip.co.uk/faxes",
      "areacodes":"https://api.surevoip.co.uk/numbers/areacodes",
      "service-status":"https://api.surevoip.co.uk/support/service-status",
      "porting":"https://api.surevoip.co.uk/porting",
      "customers":"https://api.surevoip.co.uk/customers",
      "ip-address":"https://api.surevoip.co.uk/support/ip-address",
      "echo":"https://api.surevoip.co.uk/support/echo",
      "billing":"https://api.surevoip.co.uk/billing"
   },
   "firstname":"Gavin",
   "company_name":"Suretec Systems Ltd.",
   "lastname":"Henry",
   "state":"Aberdeenshire",
   "email":"user@example.com",
   "city":"Inverurie",
   "fax":"",
   "address":"24 Cormack Park, Rothienorman",
   "company_website":"www.example.com",
   "postcode":"AB51 8GL",
   "country":"GBR",
   "phone":"01224 279484",
   "username":"XXX",
   "balance":"786666.53852",
   "creditlimit":"100000",
   "customer_resources":{
      "urls":[
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/calls",
            "title":"calls"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/calls/stats",
            "title":"call stats"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/billing/invoices",
            "title":"billing invoices"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/billing/contact",
            "title":"billing contact details"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/999-address",
            "title":"999 address"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/support/",
            "title":"support tickets"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers",
            "title":"numbers"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/countries/",
            "title":"numbers by country"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/states/",
            "title":"numbers by states"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/cities/",
            "title":"numbers by city"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/areacodes/",
            "title":"numbers by areacode"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/faxes",
            "title":"faxes"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/sms",
            "title":"sms"
         },
         {
            "href":"https://api.surevoip.co.uk/contact",
            "title":"contact"
         },
         {
            "href":"https://api.surevoip.co.uk/support/ip-address",
            "title":"ip-address"
         },
         {
            "href":"https://api.surevoip.co.uk/support/echo",
            "title":"echo"
         },
         {
            "href":"https://api.surevoip.co.uk/support",
            "title":"numbers"
         },
         {
            "href":"https://api.surevoip.co.uk/numbers/countries/",
            "title":"numbers by country"
         },
         {
            "href":"https://api.surevoip.co.uk/numbers/states/",
            "title":"numbers by states"
         },
         {
            "href":"https://api.surevoip.co.uk/numbers/cities/",
            "title":"numbers by city"
         },
         {
            "href":"https://api.surevoip.co.uk/numbers/areacodes/",
            "title":"numbers by areacode"
         },
         {
            "href":"https://api.surevoip.co.uk/support/service-status",
            "title":"service-status"
         },
         {
            "href":"https://api.surevoip.co.uk/customers/{account}/sip",
            "title":"sip"
         }
      ]
   }
}

You can POST to the top level customer resource if you are a partner or SureVoIP admin. This will create a new customer resource under your account whereby we return a 201 Created with the location header populated: 

https://api.surevoip.co.uk/partners/{partner_name}/customer/{new_customer_lives_here}

Create

curl -i -X POST -u username:password https://api.surevoip.co.uk/customers -H 'Content-Type: application/json' -T new_customer.json

using:

new_customer.json
  {
     "country":"GBR",
     "firstname":"Gavin",
     "company_name":"Suretec Systems Ltd. - API Test",
     "lastname":"Henry",
     "phone":"01224 279484",
     "state":"Aberdeenshire",
     "email":"user@example.com",
     "city":"Inverurie",
     "fax":"",
     "address":"24 Cormack Park, Rothienorman",
     "company_website":"www.example.com",
     "postcode":"AB51 8GL"
  }

This creates a customer account, SIP account and billing account.

Announcements

The announcements resource is for managing audio files you have uploaded for use with scheduled announcements when creating calls.

See the main announcements1 resource for creating new ones which appear under your account. The announcements resource under your account uses normal List Filters as it's a normal List resource.

List

Just GET to https://api.surevoip.co.uk/customers/{account}/announcements

File resource

If you have entered this in your browser: 

https://api.surevoip.co.uk/customers/{account}/announcements/JvEYs0aI4hGC-aHuK3ST4w?hypermedia=no&content-type=application/json

You would get (note the download link): 

{
   "announcement":{
      "src_ip_address":"XX.XX.XX.XX",
      "file_internal":"B3193FA0-8846-11E2-9E5D-8BA13F24ACBF.wav",
      "creation_date":"2017-03-08T23:20:00.842051000+00:00",
      "filename":"test_audio.wav",
      "url":{
         "href":"https://api.surevoip.co.uk/customers/{account}/announcements/JvEYs0aI4hGC-aHuK3ST4w",
         "title":"JvEYs0aI4hGC-aHuK3ST4w",
         "download":"https://api.surevoip.co.uk/customers/{account}/announcements/JvEYs0aI4hGC-aHuK3ST4w?download=true"
      },
      "id":"JvEYs0aI4hGC-aHuK3ST4w",
      "description":"Test via Curl",
      "size":"16201"
   }
}

delete

To delete a file just issue: 

curl -i -X DELETE -u username:password -H 'Accept: application/json' https://api.surevoip.co.uk/customers/{account}/announcements/khugsA9u4RG1OYnXPBFP4w

Calls

Customers can:

  • Create calls
  • Play audio during calls at any point
  • Schedule the call to hangup
  • Play audio at hangup
  • Transfer calls (creates a new resource has existing call/s uuid and a new/existing one)
  • List all live calls
  • Retrieve live call details
  • Control calls allowing you to:
    • Start Recording
    • Stop Recording
    • Send Digits
    • Hold
    • UnHold
    • Mute
    • UnMute
    • Hangup a call
    • Control call leg

Create and control

Methods Resource Response Description Rate Limited API Explorer on APIGee
POST /calls 201 Created Create a new call returning with the location header set Yes URL
GET /customers/{account}/calls/live 200 OK List all calls. Default last 10 calls. Yes URL
GET /customers/{account}/calls/live/{uuid} 200 OK Get call info. Yes URL
PUT /customers/{account}/calls/live/{uuid} 200 OK Control complete ongoing call Yes URL
PUT /customers/{account}/calls/live/{uuid}/{call-leg-uuid} 200 OK Control call leg Yes URL
DELETE /customers/{account}/calls/live/{uuid} 200 OK End an ongoing call. Does not remove call detail records as they are readonly. Yes URL

List Calls

Example Requests
curl -X GET -u username:password https://api.surevoip.co.uk/customers/{account}/calls/?content-type=application/json

gives: 

{
   "entries_per_page":1,
   "last_page":239,
   "current_page":1,
   "page_links":[
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=1&limit=50&offset=0",
         "title":"first_page"
      },
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=1&limit=50&offset=0",
         "title":"previous_page"
      },
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=1&limit=50&offset=0",
         "title":"current_page"
      },
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=2&limit=50&offset=0",
         "title":"next_page"
      },
      {
         "href":"https://api.surevoip.co.uk/customers/{account}/calls?page=11941&limit=50&offset=0",
         "title":"last_page"
      }
   ],
   "next_page":2,
   "previous_page":null,
   "total_entries":"11941",
   "first_page":1,
   "limit":1,
   "offset":0,
   "list":[
      {
         "cost":"0.048533",
         "stoptime":"2017-03-12T11:34:55+00:00",
         "place":"4420",
         "duration":"220",
         "caller_id":"01224279484",
         "hangup_cause":"1",
         "starttime":"2017-03-12T11:31:15+00:00",
         "phone_number_called":"442083445067"
      }
   ]
}

List filters

The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive and we also support Conditional GET and dates are in RFC3339 date/time format:

Parameter Description
toOnly show calls to this telephone phone number.
fromOnly show calls from this telephone phone number.
statusOnly show calls currently in this status. May be answered, all, ringing, in-progress, failed, busy, or no-answer. not-completed includes; failed, busy or no-answer. Default is answered
startdateOnly show telephone calls that started on this date, given as RFC3339 date/time format (2017-10-05T11:24:00Z etc.). Default is all calls from the start of today.
enddateOnly show telephone calls that ended on this date, given as RFC3339 date/time format (2017-10-05T11:24:00Z etc.). Default is all calls up until today.

Call stats

Being worked on.

Billing and Invoices

This allows you to list all your invoices (paid, unpaid, overdue) if you are a direct SureVoIP customer. If you are a customer of a SureVoIP partner then you will have to contact them.

Example Requests

curl -u username:password https://api.surevoip.co.uk/customers/{account}/billing/invoices?content-type=application/json&hypermedia=no

gives: 

{
   "invoices":[
      {
         "amount":90,
         "due_date":"2011-11-30T00:00:00",
         "status":"Unpaid",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/billing/invoices/224581",
            "title":"Invoice 224581"
         },
         "raised_date":"2011-11-23T00:00:00",
         "purchase_order":"Test",
         "invoice_number":"224581"
      },
      {
         "amount":54.03,
         "due_date":"2010-07-21T00:00:00",
         "status":"Paid",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/billing/invoices/223686",
            "title":"Invoice 223686"
         },
         "raised_date":"2010-07-21T00:00:00",
         "purchase_order":"PO Number",
         "invoice_number":"223686"
      },
      {
         "amount":-54.02,
         "due_date":"2010-06-29T00:00:00",
         "status":"Paid",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/billing/invoices/223676",
            "title":"Invoice 223676"
         },
         "raised_date":"2010-06-29T00:00:00",
         "purchase_order":"",
         "invoice_number":"223676"
      }
   ]
}

You can then get the individual details of any of the above invoices: 

curl -u username:password https://api.surevoip.co.uk/customers/{account}/billing/invoices/224581?content-type=text/html&hypermedia=no

gives: 

{
   "line_items":[
      {
         "vat_rate":"20.0000",
         "quantity":"1.0000",
         "price":"20.0000",
         "description":"Testing",
         "vat_amount":"4.0000"
      },
      {
         "vat_rate":"20.0000",
         "quantity":"1.0000",
         "price":"55.0000",
         "description":"Test 2",
         "vat_amount":"11.0000"
      }
   ],
   "exchange_rate":"1.0000",
   "status":"Unpaid",
   "raised_date":"2011-11-23T00:00:00",
   "vat_amount":"15.0000",
   "invoice_number":"224581",
   "currency":"GBP",
   "amount":90,
   "due_date":"2011-11-30T00:00:00",
   "net_amount":"75.0000",
   "purchase_order":"Test"
   "pdf_link":"https://securedwebapp.com/PermaLink/Invoices/?id=5110866&key=54A92EAB-0D10-46E6-AE30-F64C8CD"
}
Create a customer invoice

You must be an admin or partner do to this. All you need to do is POST the following JSON to the customer invoice top level resource using: 

curl -X POST -u username:password https://api.surevoip.co.uk/customers/{account}/billing/invoices?content-type=application/json&hypermedia=no -T new_invoice.json

using:

complete_new_invoice.json
  {
     "invoice_number":"123456",
     "amount":"3144.00",
     "line_items":[
        {
           "vat_rate":"20.0000",
           "quantity":"1.0000",
           "price":"    20.0000",
           "description":"Phone numbers",
           "vat_amount":"4.0000"
        },
        {
           "vat_rate":"20.0000",
           "quantity":"10.0000",
           "price":"20.0000",
           "description":"Phone numbers",
           "vat_amount":"40.0000"
        },
        {
           "vat_rate":"20.0000",
           "quantity":"100.0000",
           "price":"20.0000",
           "description":"Phone numbers",
           "vat_amount":"400.0000"
        },
        {
           "vat_rate":"20.0000",
           "quantity":"5.0000",
           "price":"20.0000",
           "description":"Phone numbers",
           "vat_amount":"20.0000"
        },
        {
           "vat_rate":"20.0000",
           "quantity":"15.0000",
           "price":"20.0000",
           "description":"Phone numbers",
           "vat_amount":"60.0000"
        }
     ]
  }
Parameter Description notes required
invoice_numberinteger for invoice numberused if present, auto-generated if notNo
amountFloat for invoice totalThis marks the invoice as PAID using this amountNo
line_itemsArray of lines itemssee next parameters for required itemsYes
vat_rateOverride the system defaultFloat - used if presentNo
quantityNumber of items in line itemFloatYes
pricePrice of itemFloatYes
descriptionFull textAlways enter somethingYes
vat_amountOverride the system defaultFloat - used if presentNo

so the bare minimum you need is:

minimum_new_invoice.json
  {
     "line_items":[
        {
           "quantity":"1.0000",
           "price":"    20.0000",
           "description":"Phone numbers",
        },
        {
           "quantity":"10.0000",
           "price":"20.0000",
           "description":"Phone numbers",
        },
        {
           "quantity":"100.0000",
           "price":"20.0000",
           "description":"Phone numbers",
        },
        {
           "quantity":"5.0000",
           "price":"20.0000",
           "description":"Phone numbers",
        },
        {
           "quantity":"15.0000",
           "price":"20.0000",
           "description":"Phone numbers",
        }
     ]
  }

Billing contact details

This allows you to list your billing address and contact detail and also update them yourself if you are a direct SureVoIP customer. If you are a customer of a SureVoIP partner then you will have to contact them.

Example Requests

curl -u username:password https://api.surevoip.co.uk/customers/{account}/billing/contact?content-type=application/json&hypermedia=no

gives: 

{
   "firstname":"Gavin",
   "website":"www.example.com",
   "accountcode":"SURE01",
   "address3":"Aberdeenshire",
   "contact":"Mr Gavin Henry",
   "lastname":"Henry",
   "mobile":"07930 323266",
   "email":"user@example.com",
   "fax":"01224 824887",
   "postcode":"AB22 8GU",
   "telephone":"01224 279484",
   "address4":"UK",
   "name":"Suretec Systems Ltd.",
   "address2":"Aberdeen",
   "created":"2009-06-18T00:00:00",
   "address1":"Unit 4, The James Gregory Centre, A.S.T.P. Bridge of Don,",
   "title":"Mr"
}

To update them you can do: 

curl -i -X PUT -u username:password https://api.surevoip.co.uk/customers/{account}/billing/contact?hypermedia=no -H 'Content-Type: application/json' -T billing_contact.json

using (which has the e-mail address changed):

billing_contact.json
{
   "firstname":"Gavin",
   "website":"www.example.com",
   "accountcode":"SURE01",
   "address3":"Aberdeenshire",
   "contact":"Mr Gavin Henry",
   "lastname":"Henry",
   "mobile":"07930 323266",
   "email":"user@example.com",
   "fax":"01224 824887",
   "postcode":"AB22 8GU",
   "telephone":"01224 279484",
   "address4":"UK",
   "name":"Suretec Systems Ltd.",
   "address2":"Aberdeen",
   "created":"2009-06-18T00:00:00",
   "address1":"Unit 4, The James Gregory Centre, A.S.T.P. Bridge of Don,",
   "title":"Mr"
}

which gives: 

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Sun, 13 Jan 2017 19:50:25 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 480
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: your_username
X-SureVoIP-API-Version: 3.50

{
   "updated using":{
      "firstname":"Gavin",
      "website":"www.example.com",
      "address3":"Aberdeenshire",
      "accountcode":"SURE01",
      "lastname":"Henry",
      "contact":"Mr Gavin Henry",
      "mobile":"07930 323266",
      "email":"user@example.com",
      "fax":"01224 824887",
      "postcode":"AB22 8GU",
      "telephone":"01224 279484",
      "address4":"UK",
      "name":"Suretec Systems Ltd.",
      "address2":"Aberdeen",
      "created":"2009-06-18T00:00:00",
      "address1":"Unit 4, The James Gregory Centre, A.S.T.P. Bridge of Don,",
      "title":"Mr"
   }
}

We will be notified of any changes and once the Event notification and WebHooks are finished so can you (partners and customers).

Note: we only allow certain fields to be updated like your email and address. Other fields are read-only and/or we control.

Support Tickets

This is being worked on at the moment.

Numbers

This resources allows you the customer to List all your numbers, update (PUT) the destination and whether it is currently activated. Partners and Admins can also provision new numbers (POST/PUT) to a customer account.

Customers will need to purchase a new number through the SureVoIP Store in order for it to appear in your list of numbers. This may change, especially if you pay by Direct Debit.

Listing

curl -i -X GET -u username:password "https://api.surevoip.co.uk/customers/{account}/numbers/?hypermedia=no&limit=5" -H 'Content-Type: application/json'

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 23:01:57 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 8004
Last-Modified: Fri, 18 Jan 2017 22:39:05 GMT
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "entries_per_page":"5",
   "last_page":4,
   "current_page":1,
   "page_links":null,
   "next_page":2,
   "previous_page":null,
   "total_entries":"20",
   "first_page":1,
   "limit":"5",
   "offset":0,
   "list":[
      {
         "country":"United Kingdom",
         "activated":"1",
         "number":"441269849575",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/441269849575",
            "title":"441269849575"
         },
         "created_date":"2017-01-16T09:56:17+00:00"
      },
      {
         "country":"United Kingdom",
         "activated":"1",
         "number":"441269849572",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/441269849572",
            "title":"441269849572"
         },
         "created_date":"2017-01-16T09:54:59+00:00"
      },
      {
         "country":"United Kingdom",
         "activated":"1",
         "number":"442035159999",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/442035159999",
            "title":"442035159999"
         },
         "created_date":"2017-01-05T16:01:54+00:00"
      },
      {
         "country":"United Kingdom",
         "activated":"1",
         "number":"01224900123",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/01224900123",
            "title":"01224900123"
         },
         "created_date":"2011-11-30T13:18:40+00:00"
      },
      {
         "country":"United Kingdom",
         "activated":"1",
         "number":"00441224900123",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/numbers/00441224900123",
            "title":"00441224900123"
         },
         "created_date":"2011-11-25T12:30:13+00:00"
      }
   ]
}

Details

curl -i -X GET -u username:password "https://api.surevoip.co.uk/customers/{account}/numbers/441224900123?hypermedia=no" -H 'Content-Type: application/json'

{
   "numbers":[
      {
         "priority":"1",
         "country":"United Kingdom",
         "activated":"1",
         "number":"441224900123",
         "destination":"SIP/01224900123@ip_address:5060",
         "country_code":"GBR",
         "number_created_date":"2010-11-10T19:41:08+00:00",
         "sent_via_sip":"1",
         "destination_created_date":"2010-11-10T19:41:27+00:00",
         "country_prefix":"44",
         "total_call_time_secs":"18276564"
      }
   ]
}

Updating

curl -i -X PUT -u username:password "https://api.surevoip.co.uk/customers/{account}/numbers/441224900999?hypermedia=no" -H 'Content-Type: application/json' -T numbers.json
SIP URI destination
numbers_to_sip_uri.json
{
   "numbers":[
      {
         "number":"441224900999",
         "destination":"sip:01224900999@pbx.example.com:5060",
         "activated":"1",
         "voip_call":"1"
      }
   ]
}

Gives: 

HTTP/1.1 100 Continue

HTTP/1.1 201 Created
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 22:39:14 GMT
Content-Type: application/json
Connection: keep-alive
Location: https://api.surevoip.co.uk/customers/{account}/numbers/441224900999
Vary: Content-Type
Content-Length: 107
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "location":"https://api.surevoip.co.uk/customers/{account}/numbers/441224900999",
   "number":"441224900999"
}
PSTN destination (Call forwarding)
numbers_to_pstn.json
{
   "numbers":[
      {
         "number":"441224900999",
         "destination":"441224824887",
         "activated":"1",
         "voip_call":"0"
      }
   ]
}

Numbers by Country

This will list your numbers by country. This is being worked on at the moment.

Numbers by State

This will list your numbers by state/shire. This is being worked on at the moment.

Numbers by city

This will list your numbers by city (including worldwide city if you have an international number). This is being worked on at the moment.

Numbers by Areacode

This will list your numbers by areacode. This is being worked on at the moment.

Faxes

The faxes resource under the customers resource is GET only. To send a fax see the top level Faxes resource.

Example Requests

curl -i -X GET -u username:password "https://api.surevoip.co.uk/customers/{account}/faxes?content-type=application/json&hypermedia=no"

gives: 

{
   "entries_per_page":50,
   "last_page":1,
   "current_page":1,
   "page_links":null,
   "next_page":null,
   "previous_page":null,
   "total_entries":"5",
   "first_page":1,
   "limit":50,
   "offset":0,
   "list":[
      {
         "status_message":"Fax transmission completed.",
         "delivered_date":"2017-01-20T10:59:25+00:00",
         "to":"441224900126",
         "filename":"test_fax.pdf",
         "creation_date":"2017-01-20T10:57:23.639102000+00:00",
         "from":"SureVoIP",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/faxes/ML5TiFVD4RGUkEHhqNQIWQ",
            "title":"ML5TiFVD4RGUkEHhqNQIWQ"
         },
         "id":"ML5TiFVD4RGUkEHhqNQIWQ",
         "sent":1,
         "called_date":"2017-01-20T10:57:44+00:00",
         "status_updated":"2017-01-20T10:59:27+00:00",
         "status_id":10
      },
      {
         "status_message":"Fax transmission completed.",
         "delivered_date":"2017-01-17T20:41:16+00:00",
         "to":"441224900126",
         "filename":"test_fax.pdf",
         "creation_date":"2017-01-17T20:40:13.831567000+00:00",
         "from":"441224824887",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/faxes/YnHydEtB4RGX-hU8qdQIWQ",
            "title":"YnHydEtB4RGX-hU8qdQIWQ"
         },
         "id":"YnHydEtB4RGX-hU8qdQIWQ",
         "sent":1,
         "called_date":"2017-01-17T20:40:28+00:00",
         "status_updated":"2017-01-17T20:41:20+00:00",
         "status_id":10
      },
      {
         "status_message":"Fax transmission completed.",
         "delivered_date":"2017-01-17T20:38:37+00:00",
         "to":"441224900126",
         "filename":"test_fax.pdf",
         "creation_date":"2017-01-17T20:37:32.393759000+00:00",
         "from":"441224824887",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/faxes/LPa4FEtB4RGyNgU8qdQIWQ",
            "title":"LPa4FEtB4RGyNgU8qdQIWQ"
         },
         "id":"LPa4FEtB4RGyNgU8qdQIWQ",
         "sent":1,
         "called_date":"2017-01-17T20:37:50+00:00",
         "status_updated":"2017-01-17T20:38:38+00:00",
         "status_id":10
      },
      {
         "status_message":"Fax transmission completed.",
         "delivered_date":"2017-01-17T20:32:10+00:00",
         "to":"441224824887",
         "filename":"test_fax.pdf",
         "creation_date":"2017-01-17T20:30:49.924860000+00:00",
         "from":"441224824887",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/faxes/QBvVJEpB4RGEBuU7qdQIWQ",
            "title":"QBvVJEpB4RGEBuU7qdQIWQ"
         },
         "id":"QBvVJEpB4RGEBuU7qdQIWQ",
         "sent":1,
         "called_date":"2017-01-17T20:31:02+00:00",
         "status_updated":"2017-01-17T20:32:12+00:00",
         "status_id":10
      },
      {
         "status_message":"Fax transmission completed.",
         "delivered_date":"2017-01-17T20:23:09+00:00",
         "to":"441224900126",
         "filename":"test_fax.pdf",
         "creation_date":"2017-01-17T20:22:04.619023000+00:00",
         "from":"441224824887",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/faxes/JMS560hB4RGXNMU7qdQIWQ",
            "title":"JMS560hB4RGXNMU7qdQIWQ"
         },
         "id":"JMS560hB4RGXNMU7qdQIWQ",
         "sent":1,
         "called_date":"2017-01-17T20:22:22+00:00",
         "status_updated":"2017-01-17T20:23:21+00:00",
         "status_id":10
      }
   ]
}

If you were to GET the first fax url, you would receive: 

{
   "fax":{
      "retries":0,
      "status_message":"Fax transmission completed.",
      "billable_duration":40,
      "to":"441224900126",
      "remote_station_ident":"SpanDSP Fax Ident",
      "from":"SureVoIP",
      "url":{
         "href":"https://api.surevoip.co.uk/customers/{account}/faxes/ML5TiFVD4RGUkEHhqNQIWQ",
         "title":"ML5TiFVD4RGUkEHhqNQIWQ"
      },
      "id":"ML5TiFVD4RGUkEHhqNQIWQ",
      "sent":1,
      "status_id":10,
      "transmit_errors":0,
      "delivered_date":"2017-01-20T10:59:25+00:00",
      "src_ip_address":"127.0.0.1",
      "filename":"test_fax.pdf",
      "creation_date":"2017-01-20T10:57:23.639102000+00:00",
      "called_date":"2017-01-20T10:57:44+00:00",
      "status_updated":"2017-01-20T10:59:27+00:00"
   }
}

SMS Messages

The SMS resource under the customers resource is GET only. To send an SMS see the top level SMS resource.

Example Requests

curl -i -X GET -u username:password "https://api.surevoip.co.uk/customers/{account}/sms?content-type=application/json&hypermedia=no"

gives: 

{
   "entries_per_page":50,
   "last_page":1,
   "current_page":1,
   "page_links":null,
   "next_page":null,
   "previous_page":null,
   "total_entries":"5",
   "first_page":1,
   "limit":50,
   "offset":0,
   "list":[
      {
         "to":"447985473495",
         "creation_date":"2017-01-09T22:20:36.362720000+00:00",
         "from":"SureVoIP",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/sms/NuNZJxA74RGFSW_OqNQIWQ",
            "title":"NuNZJxA74RGFSW_OqNQIWQ"
         },
         "id":"NuNZJxA74RGFSW_OqNQIWQ",
         "status_updated":"2017-01-09T22:20:52+00:00"
      },
      {
         "to":"447985473495",
         "creation_date":"2017-01-09T22:14:21.289314000+00:00",
         "from":"SureVoIP",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/sms/5jTKRw874RG6bVPOqNQIWQ",
            "title":"5jTKRw874RG6bVPOqNQIWQ"
         },
         "id":"5jTKRw874RG6bVPOqNQIWQ",
         "status_updated":"2017-01-09T22:14:30+00:00"
      },
      {
         "to":"447930323266",
         "creation_date":"2017-01-09T16:33:11.041481000+00:00",
         "from":"SureVoIP",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/sms/hlCSnt864RGlbDLKqNQIWQ",
            "title":"hlCSnt864RGlbDLKqNQIWQ"
         },
         "id":"hlCSnt864RGlbDLKqNQIWQ",
         "status_updated":"2017-01-09T16:33:11.041481000+00:00"
      },
      {
         "to":"447930323266",
         "creation_date":"2017-01-09T16:27:56.349739000+00:00",
         "from":"SureVoIP",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/sms/1iEA49464RGEg2PJqNQIWQ",
            "title":"1iEA49464RGEg2PJqNQIWQ"
         },
         "id":"1iEA49464RGEg2PJqNQIWQ",
         "status_updated":"2017-01-09T16:28:05+00:00"
      },
      {
         "to":"447930323266",
         "creation_date":"2017-01-08T00:00:53.587009000+00:00",
         "from":"SureVoIP",
         "url":{
            "href":"https://api.surevoip.co.uk/customers/{account}/sms/XNMR1Ys54RGmSibKqNQIWQ",
            "title":"XNMR1Ys54RGmSibKqNQIWQ"
         },
         "id":"XNMR1Ys54RGmSibKqNQIWQ",
         "status_updated":"2017-01-08T00:01:37+00:00"
      }
   ]
}

If you were to GET the first SMS url, you would receive: 

{
   "sms":{
      "status_message":"SMS delivered to handset",
      "message":"Do you love VoIP?",
      "to":"447985473495",
      "creation_date":"2017-01-09T22:20:36.362720000+00:00",
      "from":"SureVoIP",
      "url":{
         "href":"https://api.surevoip.co.uk/customers/{account}/sms/NuNZJxA74RGFSW_OqNQIWQ",
         "title":"NuNZJxA74RGFSW_OqNQIWQ"
      },
      "id":"NuNZJxA74RGFSW_OqNQIWQ",
      "sent":1,
      "status_id":11,
      "status_updated":"2017-01-09T22:20:52+00:00"
   }
}

Contact

This will allow you to submit support and sales tickets via the API which you can also do via e-mail or the web at https://support.suretecsystems.com/. This is currently being worked on.

Support IP Address

This allows you to find the IP address you connect to the API from. 

curl -i https://api.surevoip.co.uk/support/ip-address -H 'Content-Type: application/json'

gives: 

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Sun, 13 Jan 2017 15:43:44 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 28
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Version: 3.50

{
   "ip-address":"80.68.84.28"
}

Service Status

This resource lists the current service status messages found at http://www.surevoip.co.uk/help-support/service-status

Please see our full SureVoIP Status API docs which is powered by the off-network StatusPage.io

SIP

This resource allows you to get at present a read only resource state for your SIP trunk account.

Example Requests

curl -i -X GET -u username:password https://api.surevoip.co.uk/customers/{account}/sip?content-type=application/json&hypermedia=no

gives: 

{
   "entries_per_page":50,
   "last_page":1,
   "current_page":1,
   "page_links":null,
   "next_page":null,
   "previous_page":null,
   "total_entries":"1",
   "first_page":1,
   "limit":50,
   "offset":0,
   "list":[
      {
         "caller_id_name":"01224279484",
         "sip_password":"password",
         "caller_id_number":"01224279484",
         "dtmf":"RFC2833",
         "sip_username":"username",
         "sip_codecs":"ulaw,alaw,gsm,g729"
      }
   ]
}

999

This allows partners and customers to manage their 999 emergency service address details

Example Requests

Note: The integration for this is currently in progress and will be in available in the next update

Announcements

The announcements resource is for managing audio files you have uploaded for use with scheduled announcements when creating calls.

  • You can only upload wav
  • 8Khz, Mono, 16bit is most efficient for wav files. 16Khz, Mono, 16bit wav files can be used for wideband capable devices.
  • They must be less than 10mb
  • They must end in .wav
  • You can only have a maximum of 10 audio files
  • You can delete and download them. To download them simply add a &download=yes param to the end of the return URL in the Location header.

Create

curl -i -X POST -u username:password -H 'Content-Type: multipart/form-data' -H 'Accept: application/json' -F file='@test_audio.wav;type=audio/x-wav' -F description='Test announcement file upload.' https://api.surevoip.co.uk/announcements

which gives: 

HTTP/1.1 100 Continue

HTTP/1.1 202 Accepted
Server: nginx/1.2.7
Date: Fri, 8 Mar 2017 21:55:46 GMT
Content-Type: application/json
Connection: keep-alive
Location: https://api.surevoip.co.uk/customers/{account}/announcements/khugsA9u4RG1OYnXPBFP4w
Vary: Content-Type
Content-Length: 2757
X-Catalyst-Version: 5.90020
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.02

{
   "Location":"https://api.surevoip.co.uk/customers/{account}/announcements/khugsA9u4RG1OYnXPBFP4w",
   "Announcement":"File created on filesystem."
}

A GET to this resource will be the same and be able to use normal List Filters as it's a List resource. To delete a file just issue: 

curl -i -X DELETE -u username:password -H 'Accept: application/json' https://api.surevoip.co.uk/customers/{account}/announcements/khugsA9u4RG1OYnXPBFP4w

Billing

This top level resource allows SureVoIP to create (POST) invoices and new customer billing details.

Numbers

We have two resources here, the main Numbers one and the Areacode one. These are the only two resource (apart from Service Status and IP Address) that do not need authentication of any kind.

We use the Areacode one first and then the Numbers one on our Store when you buy a new number or when you search for one using the tool on the SureVoIP front page. In fact, we use the whole API as it's core to the business and not just an addon!!

You can search in the Areacode resource and then use the results to search against the Numbers one so you can Auto-populate multiple select boxes. Only unused numbers are returned, i.e. no one owns them yet.

As per normal List resources the following are supported, but we also offer more here.

Parameter Description
pagewhich page you'd like. Default page 1.
offsetWhere to start from. Only used if present.
limitGive me only this amount of results. Default 10.
number_filterAllows you to pass in digits/numbers or letters. Letters will be translated into the equivalent digit on a phone keypad. ABC = 222 etc. which is case-insensitive
areacodeAllows any numeric value so you can search per areacode. If you wish to search by place name, use the Areacode resource first to find the areacode number
number_rangeThis allows you to search using a complete number so that you can validate it at the last stage if you are for example using the API in a store (like we do). For example: 01224900111,01224900120 using a comma (,) will only return 2 number results. Use a dash (-) if you wish to check 900111 up to 900120 (20 numbers). We only allow 50 in a range to be checked

Example Requests

Just by areacode

curl "https://api.surevoip.co.uk/numbers/?hypermedia=no&areacode=01224&limit=5&page=2" -H 'Content-Type: application/json'

{
   "entries_per_page":"5",
   "last_page":155,
   "current_page":"2",
   "page_links":null,
   "next_page":3,
   "previous_page":1,
   "total_entries":"774",
   "first_page":1,
   "limit":"5",
   "offset":0,
   "list":[
      {
         "number_complete":"01224900006",
         "number":900006,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900006 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900007",
         "number":900007,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900007 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900008",
         "number":900008,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900008 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900009",
         "number":900009,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900009 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900011",
         "number":900011,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900011 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      }
   ]
}

Using number_filter also

curl "https://api.surevoip.co.uk/numbers/?hypermedia=no&areacode=01224&number_filter=Ab&limit=5&page=2" -H 'Content-Type: application/json'

Ab gets translated to 22 and only returns numbers with 22 in them (obviously :-) ): 

{
   "entries_per_page":"5",
   "last_page":4,
   "current_page":"2",
   "page_links":null,
   "next_page":3,
   "previous_page":1,
   "total_entries":"17",
   "first_page":1,
   "limit":"5",
   "offset":0,
   "list":[
      {
         "number_complete":"01224900224",
         "number":900224,
         "number_areacode":"01224",
         "number_one_off_price":250,
         "number_detail":"900224 is a <strong>gold</strong> number (&#163;250 one-off)",
         "number_quality":"gold"
      },
      {
         "number_complete":"01224900225",
         "number":900225,
         "number_areacode":"01224",
         "number_one_off_price":250,
         "number_detail":"900225 is a <strong>gold</strong> number (&#163;250 one-off)",
         "number_quality":"gold"
      },
      {
         "number_complete":"01224900226",
         "number":900226,
         "number_areacode":"01224",
         "number_one_off_price":250,
         "number_detail":"900226 is a <strong>gold</strong> number (&#163;250 one-off)",
         "number_quality":"gold"
      },
      {
         "number_complete":"01224900227",
         "number":900227,
         "number_areacode":"01224",
         "number_one_off_price":250,
         "number_detail":"900227 is a <strong>gold</strong> number (&#163;250 one-off)",
         "number_quality":"gold"
      },
      {
         "number_complete":"01224900228",
         "number":900228,
         "number_areacode":"01224",
         "number_one_off_price":250,
         "number_detail":"900228 is a <strong>gold</strong> number (&#163;250 one-off)",
         "number_quality":"gold"
      }
   ]
}

Lastly using just number_range so you can search for continuous blocks or random ones

curl "https://api.surevoip.co.uk/numbers/?hypermedia=no&number_range=01224900100-01224900109" -H 'Content-Type: application/json'

{
   "entries_per_page":50,
   "last_page":1,
   "current_page":1,
   "page_links":null,
   "next_page":null,
   "previous_page":null,
   "total_entries":9,
   "first_page":1,
   "limit":50,
   "offset":0,
   "list":[
      {
         "number_complete":"01224900101",
         "number":900101,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900101 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900102",
         "number":900102,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900102 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900103",
         "number":900103,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900103 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900104",
         "number":900104,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900104 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900105",
         "number":900105,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900105 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900106",
         "number":900106,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900106 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900107",
         "number":900107,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900107 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900108",
         "number":900108,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900108 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      },
      {
         "number_complete":"01224900109",
         "number":900109,
         "number_areacode":"01224",
         "number_one_off_price":500,
         "number_detail":"900109 is a <strong>platinum</strong> number (&#163;500 one-off)",
         "number_quality":"platinum"
      }
   ]
}

If you feel there is a missing parameter, any functionality or keys missing just let us know.

Area codes

As per normal List resources the following are supported, but we also offer more here.

Parameter Description
pagewhich page you'd like. Default page 1.
offsetWhere to start from. Only used if present.
limitGive me only this amount of results. Default 10.
area_filterAllows you to pass in digits/numbers or letters. Aberdeen, London, Glasgow etc. which are case-insensitive or for example 01224, 020, 0141
areacodeAllows any numeric value so you can search per areacode
areanameThis allows you to search using any letters from an areacode name like Ab or ab

By area_filter

curl "https://api.surevoip.co.uk/numbers/areacodes?hypermedia=no&area_filter=Ab&limit=5&page=1" -H 'Content-Type: application/json'

{
   "entries_per_page":"5",
   "last_page":3,
   "current_page":"1",
   "page_links":null,
   "next_page":2,
   "previous_page":null,
   "total_entries":"11",
   "first_page":1,
   "limit":"5",
   "offset":0,
   "list":[
      {
         "areacode":"01224",
         "areaname":"Aberdeen (01224)"
      },
      {
         "areacode":"01235",
         "areaname":"Abingdon (01235)"
      },
      {
         "areacode":"01271",
         "areaname":"Barnstable (01271)"
      },
      {
         "areacode":"01300",
         "areaname":"Cerne Abbas (01300)"
      },
      {
         "areacode":"013393",
         "areaname":"Aboyne (013393)"
      }
   ]
}

By areacode

curl "https://api.surevoip.co.uk/numbers/areacodes?hypermedia=no&areacode=22&limit=5&page=1" -H 'Content-Type: application/json'

{
   "entries_per_page":"5",
   "last_page":3,
   "current_page":"1",
   "page_links":null,
   "next_page":2,
   "previous_page":null,
   "total_entries":"15",
   "first_page":1,
   "limit":"5",
   "offset":0,
   "list":[
      {
         "areacode":"01223",
         "areaname":"Cambridge (01223)"
      },
      {
         "areacode":"01224",
         "areaname":"Aberdeen (01224)"
      },
      {
         "areacode":"01225",
         "areaname":"Bath (01225)"
      },
      {
         "areacode":"01226",
         "areaname":"Barnsley (01226)"
      },
      {
         "areacode":"01227",
         "areaname":"Canterbury (01227)"
      }
   ]
}

By areaname

curl "https://api.surevoip.co.uk/numbers/areacodes?hypermedia=no&areaname=Lon&limit=5&page=1" -H 'Content-Type: application/json'

{
   "entries_per_page":"5",
   "last_page":1,
   "current_page":"1",
   "page_links":null,
   "next_page":null,
   "previous_page":null,
   "total_entries":"4",
   "first_page":1,
   "limit":"5",
   "offset":0,
   "list":[
      {
         "areacode":"01358",
         "areaname":"Ellon (01358)"
      },
      {
         "areacode":"01951",
         "areaname":"Colonsay (01951)"
      },
      {
         "areacode":"020",
         "areaname":"London (020)"
      },
      {
         "areacode":"02871",
         "areaname":"Londonderry (02871)"
      }
   ]
}

As usual, if we have the data we'll try to give you all the information we have.

Reserve

Currently numbers need to be either POSTed to a customer resource or PUT if you updating an existing number. In order to reserve a number as a partner you would POST the number details with activated set to 1. See the next section for examples.

Provision

You can either POST multiple numbers to a customer account (https://api.surevoip.co.uk/customers/{account}/numbers) or PUT just one to a known number resource to update it or create a new one (as you're in control of the number, therefore you know the URL). You can do this only as a SureVoIP Admin or a SureVoIP partner: 

curl -i -X PUT -u username:password "https://api.surevoip.co.uk/customers/{account}/numbers/441224900999?hypermedia=no" -H 'Content-Type: application/json' -T numbers.json
numbers.json
{
   "numbers":[
      {
         "number":"441224900999",
         "destination":"sip:01224900999@pbx.example.com",
         "activated":"1"
      }
   ]
}

Note: If you are a SureVoIP admin or SureVoIP Partner you can use ported: 1 to indicate a number that is not a SureVoIP Ofcom number allocation that has been ported to SureVoIP from another Communications Provider:

ported_numbers.json
{
   "numbers":[
      {
         "number":"441224900999",
         "destination":"sip:01224900999@pbx.example.com",
         "activated":"1",
         "ported":"1",
      }
   ]
}

Gives: 

HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 22:39:14 GMT
Content-Type: application/json
Connection: keep-alive
Location: https://api.surevoip.co.uk/customers/{account}/numbers/441224900999
Vary: Content-Type
Content-Length: 107
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "location":"https://api.surevoip.co.uk/customers/{account}/numbers/441224900999",
   "number":"441224900999"
}

Calls

This is for admins. Partners and customers can do the same under their own accounts. See the customer calls resource.

Methods Resource Response Description Rate Limited API Explorer on APIGee
POST /calls 201 Created Create a new call returning with the location header set Yes URL
GET /calls/live 200 OK List all calls. Default last 10 calls. Yes URL
GET /calls/live/{uuid} 200 OK Get call info. Yes URL
PUT /calls/live/{uuid} 200 OK Control complete ongoing call Yes URL
PUT /calls/live/{uuid}/{call-leg} 200 OK Control call leg Yes URL
DELETE /calls/live/{uuid} 200 OK End an ongoing call. Does not remove call detail records as they are readonly. Yes URL

Create

curl -i -X POST -u username:password https://api.surevoip.co.uk/calls -H 'Content-Type: application/json' -T call.json

using :

call.json
{
    "to":"442035159999",
    "from":"442035159999",
    "caller_id":"01224900123"
}

which gives: 

HTTP/1.1 100 Continue

HTTP/1.1 202 Accepted
Server: nginx/1.2.7
Date: Fri, 08 Mar 2017 21:13:17 GMT
Content-Type: application/json
Content-Length: 151
Connection: keep-alive
Location: https://api.surevoip.co.uk/customers/{account}/calls/live/908dea11-fa4b-47dc-99f2-df078f5ec96d
Vary: Content-Type
X-Catalyst: 5.90020
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.02

{
   "Call":"Call creation request accepted.",
   "Location":"https://api.surevoip.co.uk/customers/{account}/calls/live/908dea11-fa4b-47dc-99f2-df078f5ec96d"
}

You will notice we return 202 Accepted and a Location header. Use this location to poll for the status of the Call. Once the WebHooks are finished we will send you this information.

Create with scheduled announcements and hangup

This is a new feature as of March 2017 whereby you can schedule an announcement to be played at any point during a call and schedule the call hangup. You can also play an audio file at hang up. The files are managed via the announcements resource. 

curl -i -X POST -u username:password https://api.surevoip.co.uk/calls -H 'Content-Type: application/json' -T sms.json

using :

call.json
{
    "to":"442035159999",
    "from":"442035159999",
    "caller_id":"01224900123"
    "announcement_at":"15",
    "announcement_id":"hgCRVfWB4hGRSEAkICyA",
    "hangup_at":"30",
    "hangup_announcement_id":"hgCRVfWB4hGRSEAkIXYCyA"
}
Key Description
announcement_atis in seconds. Just take 120 secs away from the hangup_at time for a announcement to be played 2 mins before the end of the call. If provided announcement_id is required
announcement_idis the announcement id (from https://api.surevoip.co.uk/customers/{customer}/announcements/{announcement_id}) to play for example “your call is about to end in 2 mins”. We only allow a wav file, but we may allow “words”, which will use SureVoIP provided text to speech. If provided announcement_at is required
hangup_atlength in seconds from when the call is *answered* to when the system hangs up. If “hangup_announcement_id” is present, this will be played at hangup
hangup_announcement_idthe id of a thank you announcement or similar. You can manage these as you would with any RESTful resource at https://api.surevoip.co.uk/announcements and https://api.surevoip.co.uk/customers/{customer}/announcements/{announcement_id}. It will be played at the end of the call at hangup. If provided hangup_at is required.

Stats

You can get a summary of all customers or a summary of an individual customer. This is useful for saving on queries or presenting in a “usage” or “dashboard” web/app page.

Methods Resource Response Description Rate Limited API Explorer on APIGee
GET /customers/stats (200) OK List stats with breakdown per customer. Yes URL
GET /customers/{account}/stats (200) OK List stats for one customer. Yes URL

SMS Messages

This is a feature where you can POST the following to send an SMS. SMS messages usually arrive in 3-4 seconds.

Currently we only support one SMS per request, which is not suitable for SMS/text campaigns and is limited to 160 characters. Anything more than this will be dropped and will not be split over several SMS.

This will be enabled at a later date, which will mean you can then split them over 160 chars and can send the same message to more than one mobile number.

Send

curl -i -X POST -u username:password https://api.surevoip.co.uk/sms -H 'Content-Type: application/json' -T sms.json

using :

sms.json
{
   "to":"447930323266",
   "from":"SureVoIP",
   "message":"Do you love VoIP?"
}

which gives: 

HTTP/1.1 100 Continue

HTTP/1.1 202 Accepted
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 19:35:17 GMT
Content-Type: application/json
Connection: keep-alive
Location: https://api.surevoip.co.uk/customers/{account}/sms/nrAk1Axu4RGnQInXPBFP4w
Vary: Content-Type
Content-Length: 130
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "SMS":"SMS sent, awaiting confirmation.",
   "Location":"https://api.surevoip.co.uk/customers/{account}/sms/nrAk1Axu4RGnQInXPBFP4w"
}

You will notice we return 202 Accepted and a Location header. Use this location to poll for the status of the SMS (normally the SMS will be delivered within 4 seconds). Once the WebHooks are finished we will send you this information. 

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 19:38:58 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 414
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "sms":{
      "status_message":"SMS delivered to handset",
      "message":"Do you love VoIP?",
      "to":"447930323266",
      "creation_date":"2017-03-14T19:35:17.588377000+00:00",
      "from":"SureVoIP",
      "url":{
         "href":"https://api.surevoip.co.uk/customers/{account}/sms/nrAk1Axu4RGnQInXPBFP4w",
         "title":"nrAk1Axu4RGnQInXPBFP4w"
      },
      "id":"nrAk1Axu4RGnQInXPBFP4w",
      "sent":1,
      "status_id":11,
      "status_updated":"2017-03-14T19:35:26+00:00"
   }
}

You will currently be charged 4.5p (£0.045) for this ex VAT and it will appear in your Call Detail Records suffixed with “- SMS”.

The various status messages are:

status_id status_message
1 SMS in queue
2 SMS with carrier
11 SMS delivered to handset
12 SMS rejected by handset
14 Buffered. The phone is likely off or out of range
18 Accepted by SMSC
26 Rejected by SMSC

You can also send via an HTML form. Please see the SMS send example HTML code on GitHub, which is also listed:

send_sms.html
  <!doctype html>
  <html>
      <head>
          <meta charset="utf-8">
          <title>Send an SMS via SureVoIP</title>
      </head>
      <body>
          <form action="https://api.surevoip.co.uk/sms" method="post">
            <p>To: <input type="text" name="to"> E.g. 447ReceivingMobile</p>
            <p>From: <input type="text" name="from"> E.g. 1234NoSpaces</p> 
            <p>Message: <textarea name="message"></textarea> E.g My message less than 160</p>
            <input type="submit">
          </form>
      </body>
  </html>

If you are doing this within an SMS gateway, you may need to reference this picture which shows the relevant content-type and POST raw data which many ask for:

List

This is for admins only on the top level resource.

Faxes

You can POST the following document formats to send a fax. Currently we only support one fax per request, which is not suitable for fax campaigns. This will be enabled at a later date:

Content-Type File extension Example source
application/pdf.pdfAdobe Acrobat or similar
text/plain.txtText Editor, e.g. Notepad, Vim, Emacs
text/html.htm / .htmlBrowser
image/tiff.tif / .tiffRaw scanner output

We strongly recommend only sending PDF files.

Send

curl -i -X POST -u username:password -H 'Content-Type: multipart/form-data' -H 'Accept: application/json' -F file=@test_fax.pdf -F to=441224900126 -F from=441224824887 https://api.surevoip.co.uk/faxes

which gives: 

HTTP/1.1 100 Continue

HTTP/1.1 202 Accepted
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 19:55:46 GMT
Content-Type: application/json
Connection: keep-alive
Location: https://api.surevoip.co.uk/customers/{account}/faxes/khugsA9u4RG1OYnXPBFP4w
Vary: Content-Type
Content-Length: 2757
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "Location":"https://api.surevoip.co.uk/customers/{account}/faxes/khugsA9u4RG1OYnXPBFP4w",
   "Fax":"Fax sent, awaiting confirmation."
}

You will again notice that we return 202 Accepted and a Location header. Use this location to poll for the status of the Fax (normally the Fax will be delivered within 40 seconds for a 1 page PDF). Once the WebHooks are finished we will send you this information. 

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Fri, 18 Jan 2017 19:59:50 GMT
Content-Type: application/json
Connection: keep-alive
Vary: Content-Type
Content-Length: 623
X-Catalyst-Version: 5.90112
X-SureVoIP-API-Auth-User: XXX
X-SureVoIP-API-Version: 3.50

{
   "fax":{
      "retries":0,
      "status_message":"Fax transmission completed.",
      "billable_duration":40,
      "to":"441224900126",
      "remote_station_ident":"SpanDSP Fax Ident",
      "from":"441224824887",
      "url":{
         "href":"https://api.surevoip.co.uk/customers/{account}/faxes/khugsA9u4RG1OYnXPBFP4w",
         "title":"khugsA9u4RG1OYnXPBFP4w"
      },
      "id":"khugsA9u4RG1OYnXPBFP4w",
      "sent":1,
      "status_id":10,
      "transmit_errors":0,
      "delivered_date":"2017-03-14T19:56:42+00:00",
      "src_ip_address":"89.104.229.121",
      "filename":"test_fax.pdf",
      "creation_date":"2017-03-14T19:55:46.471085000+00:00",
      "called_date":"2017-03-14T19:55:52+00:00",
      "status_updated":"2017-03-14T19:56:43+00:00"
   }
}

You will currently be charged 10p (£0.10) for this per minute ex VAT and it will appear in your Call Detail Records suffixed with “- FAX”.

The various status messages are:

status_id status_message
0Fax sent to carrier.
1Fax in queue.
5Processing fax.
10Fax transmission completed.
11Fax transmission unsuccessful.

Anything above 11 will give Fax carrier error. Please report to SureVoIP.

List

This is for admins only at the top level.

Events

Events allow you as a partner or customer can be notified by the API of when certain things happen like an incoming calls, call credit depletion etc.

This work is currently being worked on and when finished will be released on GitHub and the CPAN Open Source.

Echo

This allows you to POST or PUT data and get the same data back in the response, which in turn allows you to prove that you can speak to the API and test things like unicode etc. 

curl -i -X PUT https://api.surevoip.co.uk/support/echo -H 'Content-Type: application/json' -T test.json

Test data:

test.json
{
   "message":"This is what you sent"
}

Gives: 

{
   "echoed":{
      "message":"This is what you sent"
   }
}

IP Address

This is the same as the customer IP Address resource.

Service Status

This is the same as the customer Service Status resource, but also allows SureVoIP admins to POST new items (when that feature is complete.

Response Codes for every resource

This table will be a complete list of all resources and codes:

Methods Resource Response Description Rate Limited API Explorer on APIGee
GET /calls (200) Call Collection List all calls. Default last 10 calls. Yes URL
POST /calls (201) Location of new Call Create a new call Yes URL
GET /calls/{callid} (200) Call Details Get call info. Yes URL
PUT /calls/{callid} (202) Modified Call Control complete ongoing call Yes URL
PUT /calls/{callid}/{call-leg} (202) Modified Call Control call leg Yes URL
DELETE /calls/{callid} (200) Call ended End an ongoing call. Does not remove call detail records as they are readonly. Yes URL

Sandbox/Play Area

Please use https://sandbox.surevoip.co.uk API instead of https://api.surevoip.co.uk

Requesting access

Tips and Tricks

Code Library

Best Practices

Conditional GET

Always use the If-Modified-Since request-header on List resources like https://api.surevoip.co.uk/customers/{account}/calls 

curl -i -X GET https://api.surevoip.co.uk/customers/{account}/calls -H 'If-Modified-Since: Fri, 20 Jan 2017 10:59:26 GMT'

Hypermedia NO

If you don't need it, switch it off to make the payload smaller 

&hypermedia=no

Date and Time

All our Date and Time values are as per the RFC3339 date/time format, an ISO 8601 profile, defined at http://tools.ietf.org/html/rfc3339

For example: 

2017-10-05T11:24:00Z

Use caching

If you are building a web page using the SureVoIP API, we recommend that you do all API requests on the server side, and if possible cache them. If you get any substantial traffic, you do not want to call the API each time you get a page hit, since this may cause you to hit the request limit faster than expected. In general, whenever you can cache data, do so.

Send your user credentials in a preemptive manner

Some HTTP clients omit the authentication header, and make a second request with the header when they get a 401 Unauthorized response. Please make sure you send the credentials directly, to avoid unnecessary requests.

Use common sense

Should be simple enough. For example, don't check for the status of a check every other second. The highest check resolution is one minute. Checking more often than that won't give you much of an advantage.

The Internet is unreliable

Networks in general are unreliable, and particularly one as large and complex as the Internet. Your application should not assume it will always get an answer. There may be timeouts.

Change log

To do

Additional RESTful resources

Core

Partners

New
List
Update
Delete

Porting

New
List
Update
Delete

Store

Products

Brands

Categories

Orders

Hosted

Inbound routes

Outbound routes

Users

Extensions

Contacts

Queues

Conferences

IVRs

Recordings

Time conditions

Voicemails

Music On Hold

Ring Groups

Follow Me

Call Forward

Do Not Disturb

Registrations

Calls

Faxes

Hot desking

Support

If you have questions or problems, please email:

  • api_documentation.txt
  • Last modified: 2024/03/25 16:21
  • by 127.0.0.1