TIM4biz API support, tutorial and sample code

The TIM4biz API allows you to create applications that access your PBX call accounting records, settings and other data.

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.

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 too long a period was requested or a GET request was made instead of a POST.
• 401 - Unauthorized.
• 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

Other response headers

• TIM4biz-API-URL: The APIs are moving from tim4biz.com to api.tim4biz.com
• TIM4biz-Authentication: Recommend changing from BEARER to BASIC authentication

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. This example won't succeed without a TIM4biz call accounting licence.

/// <summary> /// Copyright © TIM IP Pty Limited 2024-2025 /// Description: TIM4biz C# API HTTP GET example /// Created: 2024-12-13 06:03 /// </summary> using Newtonsoft.Json; using System.Diagnostics; using System.IO; using System.Net; /// <summary> /// TIM4biz API ExtensionTotal simple example /// </summary> private void ExtensionTotalExampleSimple(string username, string password) { // url string url = "https://tim4biz.com/api/reports/ExtensionTotal?lastminutes=1440"; // authorization in header HttpWebRequest wrGETURL = (HttpWebRequest)WebRequest.Create(url); wrGETURL.ContentType = "accept: application/json"; var userpass = System.Text.Encoding.UTF8.GetBytes(username + ":" + password); string encode = System.Convert.ToBase64String(userpass); wrGETURL.Headers.Add("Authorization", "BASIC " + encode); // GET Stream objStream = wrGETURL.GetResponse().GetResponseStream(); StreamReader objReader = new StreamReader(objStream); string response = objReader.ReadToEnd(); // response Debug.WriteLine(response); // parse 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 + "]"); } } } // response headers WebHeaderCollection headers = wrGETURL.GetResponse().Headers; for (Int32 nIndex = 0; nIndex < headers.Count; nIndex++) { if (headers.AllKeys[nIndex].ToLower().Contains("tim4biz")) Debug.WriteLine(headers.AllKeys[nIndex] + ": " + headers.GetValues(nIndex)[0]); } }

Simple Python example - HTTP GET

Simple Python code demonstrating making a call to the ExtensionTotal method. This example won't succeed without a TIM4biz call accounting licence.

You may need to install the requests and sys packages before running the sample, for example:

$ python -m pip install requests
$ python -m pip install sys

# Copyright © TIM IP Pty Limited 2024-2025 # Description: TIM4biz Python API HTTP GET example # Created: 2024-12-13 06:27 import base64 import json import requests import sys # check command line if len(sys.argv) < 3: sys.exit("usage:\r\nexttotal.py <username> <password>\r\n") # url url = "https://tim4biz.com/api/reports/ExtensionTotal?lastminutes=60" # authorization in header # userpass is username:password built from command line username = sys.argv[1] password = sys.argv[2] userpass = username + ":" + password encoded_bytes = base64.b64encode(userpass.encode('utf-8')) encoded_str = encoded_bytes.decode('utf-8') headers = { "Content-Type": "application/json", "Authorization": "BASIC " + encoded_str} # GET response = requests.get(url, headers = headers) # dump formatted response of first 2 items if they exist count = min(2, len(response.json())) for x in range(0, count): print(json.dumps(response.json()[x], indent=2))

Simple C# example - HTTP POST

Simple C# code demonstrating making a call to the SetSMS method. This example won't succeed without a TIM4biz messaging licence.

/// <summary> /// Copyright © TIM IP Pty Limited 2024-2025 /// Description: TIM4biz C# API HTTP POST example /// Created: 2024-12-13 06:23 /// </summary> using System.Diagnostics; using System.IO; using System.Net; /// <summary> /// TIM4biz API SetSMS simple example /// </summary> private void SetSMSExample(string username, string password) { // url string url = "https://tim4biz.com/api/settings/SetSMS?number=0409xxxxxx&message=This%20is%20a%20test"; // authorization in header WebClient wc = new WebClient(); var userpass = System.Text.Encoding.UTF8.GetBytes(username + ":" + password); string encode = System.Convert.ToBase64String(userpass); wc.Headers.Add("Authorization", "BASIC " + encode); // POST NameValueCollection nvcPOSTParams = new NameValueCollection(); byte[] bytes = wc.UploadValues(url, "POST", nvcPOSTParams); // response string response = Encoding.ASCII.GetString(bytes); Debug.WriteLine(response); // response headers WebHeaderCollection headers = wc.ResponseHeaders; for (Int32 nIndex = 0; nIndex < headers.Count; nIndex++) { if (headers.AllKeys[nIndex].ToLower().Contains("tim4biz")) Debug.WriteLine(headers.AllKeys[nIndex] + ": " + headers.GetValues(nIndex)[0]); } }

Simple Python example - HTTP POST

Simple Python code demonstrating making a call to the SetSMS method. This example won't succeed without a TIM4biz messaging licence.

You may need to install the requests and sys packages before running the sample, for example:

$ python -m pip install requests
$ python -m pip install sys

# Copyright © TIM IP Pty Limited 2024-2025 # Description: TIM4biz Python API HTTP GET example # Created: 2024-12-13 06:31 import base64 import requests import sys # check command line if len(sys.argv) < 3: sys.exit("usage:\r\nsetsms.py <username> <password>\r\n") # url url = "https://tim4biz.com/api/settings/SetSMS?number=0409xxxxxx&message=This%20is%20Python"; # authorization in header # userpass is username:password built from command line username = sys.argv[1] password = sys.argv[2] userpass = username + ":" + password encoded_bytes = base64.b64encode(userpass.encode('utf-8')) encoded_str = encoded_bytes.decode('utf-8') headers = { "Content-Type": "application/json", "Authorization": "BASIC " + encoded_str} # POST response = requests.post(url, headers = headers)

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.