{{tag>API}} ====== 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 [[http://curl.haxx.se/|curl]] so you can just copy and paste them for testing. We will have a [[api_documentation#sandbox_play_area|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|API documentation]] explains the format for raw HTTP calls to the SureVoIP API. We also have [[api_documentation:libraries|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 [[api_documentation#http_verbs|HTTP Verbs]] below and send the same formats as described in the [[api_documentation#response_formats|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 [[api_documentation#http_verbs|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/plain|Plain text format| |text/xml|XML format| |text/html|Basic HTML| |application/json|[[http://www.json.org/|JSON]]| |application/xml|XML format| |text/javascript|JSONP - 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-dumper|[[http://search.cpan.org/perldoc?Data%3A%3ADumper|Data::Dumper]] format| |text/x-data-denter|[[http://search.cpan.org/perldoc?Data%3A%3ADenter|Data::Denter]] format| |text/x-data-taxi|[[http://search.cpan.org/perldoc?Data%3A%3ATaxi|Data::Taxi]] format| |application/x-storable|[[http://search.cpan.org/perldoc?Storable|Storable format]] format| |application/x-freezethaw|[[http://search.cpan.org/perldoc?FreezeThaw|FreezeThaw]] format| |text/x-config-general|[[http://search.cpan.org/perldoc?Config%3A%3AGeneral|Config::General]] format| |text/x-php-serialization|[[http://search.cpan.org/perldoc?PHP%3A%3ASerialization|PHP::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 [[http://www.surevoip.co.uk|SureVoIP]] account is required. ===== Basic Authentication ==== The credentials used for accessing the API via [[http://en.wikipedia.org/wiki/Basic_access_authentication|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 [[api_documentation#sandbox_play_area|Sandbox/Play area]] for more info. ===== OAuth 2.0 protocol ===== SureVoIP's RESTful API uses the [[http://oauth.net/2//|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 [[http://github.com|GitHub]] and [[http://search.cpan.org|the CPAN]] [[http://www.opensource.org|Open Source]] when the docs are written). {{:oauth2.0_diagrams.pdf|OAuth 2 Flowcharts}} ====== Getting Started ====== You can test the [[api_documentation#resources|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 [[https://api.surevoip.co.uk/support/ip-address|support/ip-address]] and [[https://api.surevoip.co.uk/support/service-status|support/service-status]] * can I accurately send and receive data, including accounting for Unicode/decode/encode issues? This covered by [[https://api.surevoip.co.uk|support/echo]] * can I authenticate? This covered by any resource that requires authentication, for example: [[https://api.surevoip.co.uk/customers|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) ====== Code Examples ====== We are slowly adding various code examples to the [[https://github.com/suretec/SureVoIP-API-Examples|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 [[http://github.com|GitHub]] and [[http://search.cpan.org|the CPAN]] [[http://www.opensource.org|Open Source]]). We'll send out an email and [[http://www.surevoip.co.uk/blog|blog post]] when ready. ====== RESTful Resources ====== The following sections describe in detail the resources available, what you can send, what [[api_documentation#response_formats|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 [[http://curl.haxx.se/|curl]]. For a complete list of resources and response codes etc. please see the [[api_documentation#response_codes|Response Codes]] table. By default you will see [[http://en.wikipedia.org/wiki/Hypermedia|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 [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html|Conditional GET]] and dates are in [[http://search.cpan.org/~drolsky/DateTime-Format-Strptime-1.5000/lib/DateTime/Format/Strptime.pm|strptime format]]: ^ Parameter ^ Description ^ |page|which page you'd like| |offset|Where to start from| |limit|Give 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: { "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 [[#create_with_scheduled_announcements_and_hangup|scheduled announcements when creating calls]]. See the main [[#announcements|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_resources|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 [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html|Conditional GET]] and dates are in [[api_documentation#date_and_time|RFC3339 date/time format]]: ^ Parameter ^ Description ^ |to|Only show calls **to** this telephone phone number.| |from|Only show calls **from** this telephone phone number.| |status|Only 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**| |startdate|Only show telephone calls that started on this date, given as [[api_documentation#date_and_time|RFC3339 date/time format]] (2017-10-05T11:24:00Z etc.). Default is all calls from the start of today.| |enddate|Only show telephone calls that ended on this date, given as [[api_documentation#date_and_time|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 [[http://www.surevoip.co.uk/partners|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: { "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_number|integer for invoice number|used if present, auto-generated if not|No| |amount|Float for invoice total|This marks the invoice as PAID using this amount|No| |line_items|Array of lines items|see next parameters for required items|Yes| |vat_rate|Override the system default|Float - used if present|No| |quantity|Number of items in line item|Float|Yes| |price|Price of item|Float|Yes| |description|Full text|Always enter something|Yes| |vat_amount|Override the system default|Float - used if present|No| so the bare minimum you need is: { "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): { "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|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 [[api_documentation#provision|provision new numbers]] (POST/PUT) to a customer account. Customers will need to purchase a new number through the [[http://www.surevoip.co.uk|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":[ { "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":[ { "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 [[api_documentation#faxes1|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 [[api_documentation#sms_messages1|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 [[http://status.surevoip.co.uk/api|SureVoIP Status API docs]] which is powered by the off-network [[https://www.statuspage.io/|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 [[#create_with_scheduled_announcements_and_hangup|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 [[http://www.surevoip.co.uk/store|Store]] when you buy a new number or when you search for one using the tool on the [[http://www.surevoip.co.uk|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 [[api_documentation#area_codes|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 [[api_documentation#list_resources|List resources]] the following are supported, but we also offer more here. ^ Parameter ^ Description ^ |page|which page you'd like. Default page 1.| |offset|Where to start from. Only used if present.| |limit|Give me only this amount of results. Default 10.| |number_filter|Allows 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| |areacode|Allows any numeric value so you can search per areacode. If you wish to search by place name, use the [[api_documentation#area_codes|Areacode resource]] first to find the areacode number| |number_range|This 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 platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900007", "number":900007, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900007 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900008", "number":900008, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900008 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900009", "number":900009, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900009 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900011", "number":900011, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900011 is a platinum number (£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 gold number (£250 one-off)", "number_quality":"gold" }, { "number_complete":"01224900225", "number":900225, "number_areacode":"01224", "number_one_off_price":250, "number_detail":"900225 is a gold number (£250 one-off)", "number_quality":"gold" }, { "number_complete":"01224900226", "number":900226, "number_areacode":"01224", "number_one_off_price":250, "number_detail":"900226 is a gold number (£250 one-off)", "number_quality":"gold" }, { "number_complete":"01224900227", "number":900227, "number_areacode":"01224", "number_one_off_price":250, "number_detail":"900227 is a gold number (£250 one-off)", "number_quality":"gold" }, { "number_complete":"01224900228", "number":900228, "number_areacode":"01224", "number_one_off_price":250, "number_detail":"900228 is a gold number (£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 platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900102", "number":900102, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900102 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900103", "number":900103, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900103 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900104", "number":900104, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900104 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900105", "number":900105, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900105 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900106", "number":900106, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900106 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900107", "number":900107, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900107 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900108", "number":900108, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900108 is a platinum number (£500 one-off)", "number_quality":"platinum" }, { "number_complete":"01224900109", "number":900109, "number_areacode":"01224", "number_one_off_price":500, "number_detail":"900109 is a platinum number (£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 [[api_documentation#list_resources|List resources]] the following are supported, but we also offer more here. ^ Parameter ^ Description ^ |page|which page you'd like. Default page 1.| |offset|Where to start from. Only used if present.| |limit|Give me only this amount of results. Default 10.| |area_filter|Allows you to pass in digits/numbers or letters. Aberdeen, London, Glasgow etc. which are case-insensitive or for example 01224, 020, 0141| |areacode|Allows any numeric value so you can search per areacode| |areaname|This 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 [[http://www.surevoip.co.uk/partners|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":[ { "number":"441224900999", "destination":"sip:01224900999@pbx.example.com", "activated":"1" } ] } Note: If you are a SureVoIP admin or [[http://www.surevoip.co.uk/partners/partner|SureVoIP Partner]] you can use **ported: 1** to indicate a number that is not a [[http://www.surevoip.co.uk/about/ofcom|SureVoIP Ofcom]] number allocation that has been [[http://www.surevoip.co.uk/products/number-porting|ported to SureVoIP]] from another Communications Provider: { "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 [[api_documentation#calls|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 : { "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 [[api_documentation#event_notification_and_webhooks|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|announcements resource]]. curl -i -X POST -u username:password https://api.surevoip.co.uk/calls -H 'Content-Type: application/json' -T sms.json using : { "to":"442035159999", "from":"442035159999", "caller_id":"01224900123" "announcement_at":"15", "announcement_id":"hgCRVfWB4hGRSEAkICyA", "hangup_at":"30", "hangup_announcement_id":"hgCRVfWB4hGRSEAkIXYCyA" } ^ Key ^ Description ^ |**announcement_at**|is 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_id**|is 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_at**|length 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_id**|the 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 : { "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 [[api_documentation#event_notification_and_webhooks|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 [[api_documentation#calls|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 [[https://github.com/suretec/SureVoIP-API-Examples/tree/master/code/html/sms|SMS send example HTML code on GitHub]], which is also listed: Send an SMS via SureVoIP

To: E.g. 447ReceivingMobile

From: E.g. 1234NoSpaces

Message: E.g My message less than 160

 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: {{::send_sms_via_html_firebug_on_firefox.png?500|}} ==== 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|.pdf|Adobe Acrobat or similar| |text/plain|.txt|Text Editor, e.g. Notepad, Vim, Emacs| |text/html|.htm / .html|Browser| |image/tiff|.tif / .tiff|Raw 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 [[api_documentation#event_notification_and_webhooks|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 [[api_documentation#calls|Call Detail Records]] suffixed with "- FAX". The various status messages are: ^ status_id ^ status_message ^ |0|Fax sent to carrier.| |1|Fax in queue.| |5|Processing fax.| |10|Fax transmission completed.| |11|Fax 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 [[http://github.com|GitHub]] and [[http://search.cpan.org|the CPAN]] [[http://www.opensource.org|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: { "message":"This is what you sent" } Gives: { "echoed":{ "message":"This is what you sent" } } ===== IP Address ===== This is the same as the customer [[api_documentation#support_ip_address|IP Address]] resource. ===== Service Status ===== This is the same as the customer [[api_documentation#service_status|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-support@surevoip.co.uk|SureVoIP API Support]] * [[api-bugs@surevoip.co.uk|SureVoIP API Bugs]] * [[http://twitter.com/SureVoIPAPI|SureVoIP API on Twitter]]