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

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.

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.

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

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

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

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

Used for retrieving resources.

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

Used for replacing resources or collections.

Used for deleting resources.

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:

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

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

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

We support for all resources:

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

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

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

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 is needed in order to use the SureVoIP API, and for this a SureVoIP account is required.

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.

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

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:

• echo: https://api.surevoip.co.uk/support/echo (POST and PUT only)
• ip-address: https://api.surevoip.co.uk/support/ip-address (GET)
• service-status: https://api.surevoip.co.uk/support/service-status (GET)

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

Please check there from time to time.

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.

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

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:

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":[
      {
         ....
      },
      {
         ....
      },
      {
         ....
      }
   ]
}

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.

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}

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.

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.

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

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

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

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

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

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:

Being worked on.

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.

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

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

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

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.

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.

This is being worked on at the moment.

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.

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

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

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

numbers_to_pstn.json

{
   "numbers":[
      {
         "number":"441224900999",
         "destination":"441224824887",
         "activated":"1",
         "voip_call":"0"
      }
   ]
}

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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.

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

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

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.

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

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

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.

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

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

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

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.

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.

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

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

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.

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

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.

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.

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:

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:

This is for admins only on the top level resource.

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:

We strongly recommend only sending PDF files.

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:

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

This is for admins only at the top level.

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.

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

This is the same as the customer IP Address resource.

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

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

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

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'

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

&hypermedia=no

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

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.

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.

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.

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.

If you have questions or problems, please email:

• SureVoIP API Support
• SureVoIP API Bugs
• SureVoIP API on Twitter