TIM4biz API support, tutorial and sample code

The TIM4biz API allows you to create applications that access your PBX call accounting records.

Tutorial sample code for C# and Python is provided below. The TIM4biz API definitions are described on the API homepage at https://tim4biz.com/api/.

Authorization

Access to the TIM4biz APIs requires a TIM4biz account, product licence and an API access enabled username.

API calls require a bearer token. This bearer token can be created below for inclusion in your application and can be created for testing on the API definition page.

The bearer token created is tied to your TIM4biz username and expires with your password.

Create bearer token

TIM4biz API bearer token

On the API definition page each method allows you to test it with a Try it out button. Before you can test the APIs you must authorize on that page. The bearer token created is the same one created above and will be displayed in the generated code.

1. Go to https://tim4biz.com/api/
2. Click the green Authorize button on the right.
   The Available authorizations window is displayed.
3. Enter your TIM4biz username in client_id
4. Enter your TIM4biz password in client_secret
5. Click the green Authorize button
   If authorized a green Logout and a black Close button will appear.
6. Click the Close button.

When you have finished testing the methods click the Authorize button and click Logout.

Response codes

TIM4biz API response codes indicate success or error of the API call.

• 200 - Success.
• 400 - Bad request, invalid parameter supplied, for example datetime range was not supplied or a GET request was made instead of a POST.
• 401 - Unauthorized, invalid bearer token.
• 403 - Forbidden, not licenced.
• 404 - Not found, supplied value not found.
• 429 - Too Many Requests, your rate limit has been exceeded or you have a rate limit of zero.

Rate limit response headers

The TIM4biz API has a rate limit based on the accumulated number of calls a company can make per 60 minutes. The default value can be increased if required.

TIM4biz API responses include headers that provide you with your rate limit status.

• TIM4biz-Rate-Limit-Limit: The configured number of API calls per 60 minutes
• TIM4biz-Rate-Limit-Remaining: The number of API calls remaining before hitting the 60-minute rate limit
• TIM4biz-Rate-Limit-Limit-24-Hours: The configured number of API calls per 24 hours
• TIM4biz-Rate-Limit-Remaining-24-Hours: The number of API calls remaining before hitting the 24-hour rate limit

API example calls

The TIM4biz API definitions are described on the TIM4biz API homepage at https://tim4biz.com/api/.

Simple TIM4biz API calls are demonstrated below. Alternatively, you can use the Swagger Editor to create a class library to access TIM4biz API.

Simple C# example - HTTP GET

Simple C# code demonstrating making a call to the ExtensionTotal method. Replace the bearer token YOURBEARERTOKEN with your token. This example won't succeed without a TIM4biz call accounting licence.

using Newtonsoft.Json; using System.Diagnostics; using System.IO; using System.Net; /// <summary> /// TIM4biz API ExtensionTotal simple example /// </summary> private void ExtensionTotalExampleSimple() { // curl example from https://tim4biz.com/api // curl -X GET "https://tim4biz.com/api/reports/ExtensionTotal?lastminutes=1440" -H "accept: application/json" // -H "authorization: Bearer YOURBEARERTOKEN" // build request in url, authorization in header string url = "https://tim4biz.com/api/reports/ExtensionTotal?lastminutes=1440"; HttpWebRequest wrGETURL = (HttpWebRequest)WebRequest.Create(url); wrGETURL.ContentType = "accept: application/json"; wrGETURL.Headers.Add("Authorization", "Bearer YOURBEARERTOKEN"); // request Stream objStream = wrGETURL.GetResponse().GetResponseStream(); StreamReader objReader = new StreamReader(objStream); string response = objReader.ReadToEnd(); // response if (!string.IsNullOrEmpty(response)) { Newtonsoft.Json.Linq.JArray jarray = (Newtonsoft.Json.Linq.JArray)JsonConvert.DeserializeObject(response); if (jarray != null) { for (Int32 index = 0; index < jarray.Count; index++) { Newtonsoft.Json.Linq.JObject jobject = (Newtonsoft.Json.Linq.JObject)jarray[index]; string extension = jobject["extension"].ToString(); Int32 inbound = Int32.Parse(jobject["inbound"].ToString()); Int32 outbound = Int32.Parse(jobject["outbound"].ToString()); // output Debug.WriteLine("extension[" + extension + "] in[" + inbound + "] out[" + outbound + "]"); } Debug.WriteLine("Limit[" + wrGETURL.GetResponse().Headers["TIM4biz-Rate-Limit-Limit"] + "]"); Debug.WriteLine("Remaining[" + wrGETURL.GetResponse().Headers["TIM4biz-Rate-Limit-Remaining"] + "]"); } } }

Simple Python example - HTTP GET

Simple Python code demonstrating making a call to the ExtensionTotal method. Replace the bearer token YOURBEARERTOKEN with your token. This example won't succeed without a TIM4biz call accounting licence.

You may need to install the requests package before running the sample, for example:

$ python -m pip install requests

import json import requests # build request in url, authorization in header url = "https://tim4biz.com/api/reports/ExtensionTotal?lastminutes=60" headers = { "Content-Type": "application/json", "Authorization": "Bearer YOURBEARERTOKEN" } # request response = requests.get(url, headers = headers) # dump formatted first item if it exists if len(response.json()) > 0 : print(json.dumps(response.json()[0], indent=2))

Simple C# example - HTTP POST

Simple C# code demonstrating making a call to the SetSMS method. Replace the bearer token YOURBEARERTOKEN with your token. This example won't succeed without a TIM4biz messaging licence.

using System.Diagnostics; using System.IO; using System.Net; /// <summary> /// TIM4biz API SetSMS simple example /// </summary> private void SetSMSExample() { // curl example from https://tim4biz.com/api // curl -X POST "https://tim4biz.com/api/settings/SetSMS?number=0409xxxxxx&message=This%20is%20a%20test" // -H "accept: application/json" -H "authorization: Bearer YOURBEARERTOKEN" // build request in url, authorization in header string url = "https://tim4biz.com/api/settings/SetSMS?number=0409xxxxxx&message=This%20is%20a%20test"; NameValueCollection nvcPOSTParams = new NameValueCollection(); WebClient wc = new WebClient(); wc.Headers.Add("Authorization", "Bearer YOURBEARERTOKEN"); byte[] bytes = wc.UploadValues(url, "POST", nvcPOSTParams); string response = Encoding.ASCII.GetString(bytes); // response Debug.WriteLine(response); // headers for (Int32 index = 0; index < wc.Headers.Count; index++) { if (wc.Headers.Keys[index].StartsWith("TIM4biz")) Debug.WriteLine(wc.Headers.Keys[index] + " " + wc.Headers[index]); } }

Simple Python example - HTTP POST

Simple Python code demonstrating making a call to the SetSMS method. Replace the bearer token YOURBEARERTOKEN with your token. This example won't succeed without a TIM4biz messaging licence.

import requests # build request in url, authorization in header url = "https://tim4biz.com/api/settings/SetSMS?number=0409xxxxxx&message=This%20is%20Python"; headers = { "Content-Type": "application/json", "Authorization": "Bearer YOURBEARERTOKEN" } # request response = requests.post(url, headers = headers)

Swagger generated C# class library example

The Swagger Editor at https://editor.swagger.io/ can be used to generate a class library to access TIM4biz API.

1. Under the title on the TIM4biz API page at https://tim4biz.com/api/ is a link to the TIM4biz API JSON definition. Click on that link to open the TIM4biz API JSON definition.
   The TIM4biz API JSON definition is displayed.
2. Open the Swagger Editor at https://editor.swagger.io/.
3. Copy the contents of the TIM4biz API JSON file and paste it into the left pane of the Swagger Editor.
   There may be a popup window asking if you wish to convert JSON to YAML, select OK. The TIM4biz API is loaded into the right pane.
4. At the top of the window select Generate Client and select your target language.
   A download is produced, for example, csharp-client-generated.zip, save it to your computer.
5. Add the IO.Swagger generated class library to your project and call the generated APIs.
6. C# code demonstrating making a call to the ExtensionTotal method via the Swagger generated library. Replace the bearer token YOURBEARERTOKEN with your token.
   
   using IO.Swagger.Api; using System.Diagnostics; /// <summary> /// TIM4biz API ExtensionTotal Swagger C# example /// </summary> private void ExtensionTotalExampleSwaggerCsharp() { IO.Swagger.Client.Configuration configuration = new IO.Swagger.Client.Configuration(); configuration.AccessToken = "YOURBEARERTOKEN"; ReportsApi report = new ReportsApi(configuration); List<IO.Swagger.Model.StandardTotal> results = report.ExtensionTotal("", null, null, 1440); for (Int32 index = 0; index < results.Count; index++) { IO.Swagger.Model.StandardTotal r = results[index]; // output Debug.WriteLine("extension[" + r.Extension + "] in[" + r.Inbound + "] out[" + r.Outbound + "]"); } }

API page not showing updates

After an update to the main API page sometimes it is necessary to force your browser to show the latest API version. The usual Ctrl+F5 or Shift+Command+R may not be enough. Follow the following steps to display the latest API version.

1. Go to the main API page at https://tim4biz.com/api/
2. Click on the JSON link at the top of the page https://tim4biz.com/api/swagger.json
   The swagger.json page is opened
3. Press Ctrl+F5 (or Shift+Command+R as appropriate)
   The swagger.json page is refresed
4. Return to the main page at https://tim4biz.com/api/
5. Press Ctrl+F5
   The API page is (finally) refreshed

API GET or POST

APIs are requested as either an HTTP GET or an HTTP POST. Each API heading indicates whether it should be called via a GET or a POST.

• GET is used for requesting information without changing the information.
• POST is used to insert, update or delete remote data.
• Using the incorrect request type will generate a 400 response code.