Developers

TIM4biz API support, tutorials & sample code

Build applications that access your PBX call accounting records, settings and other data. Read the response-code reference, copy a working sample in C# or Python, and ship faster.

REST / JSON Rate-limited GET & POST
01

Authorization

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

Need access? Contact us to enable API access on your account and to raise your rate limit above zero.
02

Response codes

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

200 Success

The request completed successfully.

400 Bad request

Invalid parameter — for example, a missing datetime range, a period that is too long, or a GET sent where a POST was required.

401 Unauthorized

Authentication is missing or invalid.

403 Forbidden

The account is not licenced for this API.

404 Not found

The supplied value could not be located.

429 Too many requests

The rate limit has been exceeded, or your rate limit is currently zero.

03

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 on request — please contact us to enable API access and lift the rate limit above zero.

Header Description
TIM4biz-Rate-Limit-Limit Configured number of API calls per 60 minutes.
TIM4biz-Rate-Limit-Remaining Calls remaining before hitting the 60-minute rate limit.
TIM4biz-Rate-Limit-Limit-24-Hours Configured number of API calls per 24 hours.
TIM4biz-Rate-Limit-Remaining-24-Hours Calls remaining before hitting the 24-hour rate limit.
04

Other response headers

Header Description
TIM4biz-API-URL The APIs are moving from tim4biz.com to api.tim4biz.com.
TIM4biz-Authentication Recommendation to migrate from BEARER to BASIC authentication.
05

API example calls

The TIM4biz API definitions are documented on the API homepage. The samples below demonstrate simple calls; you can also use the Swagger Editor to generate a class library.

Simple C# code demonstrating a call to the ExtensionTotal method. The example needs a TIM4biz call accounting licence to succeed.

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var http = new HttpClient();
        var userpass = Encoding.UTF8.GetBytes(username + ":" + password);
        string encode = Convert.ToBase64String(userpass);
        http.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Basic", encode);

        var url = "https://api.tim4biz.com/api/reports/ExtensionTotal?lastminutes=1440";

        var response = await http.GetAsync(url);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Simple Python code demonstrating a call to the ExtensionTotal method. The example needs a TIM4biz call accounting licence to succeed. You may need to install the requests or sys packages first.

$ python -m pip install requests
$ python -m pip install sys
import base64
import json 
import requests
import sys

# check command line
if len(sys.argv) < 3:
    sys.exit("usage: exttotal.py username password")

# 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))


Save the above as exttotal.py. Then execute:

$ python exttotal.py username password

Simple C# code demonstrating a call to the SetSMS method. The example needs a TIM4biz messaging licence to succeed.

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var http = new HttpClient();
        var userpass = Encoding.UTF8.GetBytes(username + ":" + password);
        string encode = Convert.ToBase64String(userpass);
        http.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Basic", encode);

        var json = "{\"number\":\"+61000000000\",\"message\":\"Hello from TIM4biz\"}";
        var body = new StringContent(json, Encoding.UTF8, "application/json");
        var response = await http.PostAsync(
            "https://api.tim4biz.com/api/settings/SetSMS", body);

        System.Console.WriteLine((int)response.StatusCode);
    }
}

Simple Python code demonstrating a call to the SetSMS method. The example needs a TIM4biz messaging licence to succeed. You may need to install the requests or sys packages first.

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

# check command line
if len(sys.argv) < 3:
    sys.exit("usage: setsms.py username password")

# url & body
url = "https://api.tim4biz.com/api/settings/SetSMS";
body = {"number": "+61000000000", "message": "Hello from TIM4biz/Python"}

# 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, json = body)


Save the above as setsms.py. Then execute.

$ python setsms.py username password

Simple VB.NET code demonstrating a call to the ExtensionTotal method. The example needs a TIM4biz call accounting licence to succeed.

Imports System.IO
Imports System.Net

Private Sub ButtonExtTotal_Click(sender As Object, e As EventArgs) Handles ButtonExtTotal.Click
    ' url
    Dim Url As String = "https://api.tim4biz.com/api/reports/ExtensionTotal?lastminutes=1440"

    ' request
    Dim request As HttpWebRequest = DirectCast(WebRequest.Create(Url), HttpWebRequest)
    request.Method = "GET"
    request.ContentType = "accept: application/json"
    'request.Headers.Add("Authorization", "Basic " + UserPass())

    ' convert bytes to string encoded as base 64 and add as header
    Dim plainTextBytes() As Byte = System.Text.Encoding.UTF8.GetBytes(TextBoxUser.Text + ":" + TextBoxPass.Text)
    Dim encode As String = System.Convert.ToBase64String(plainTextBytes)
    request.Headers.Add("Authorization", "Basic " + encode)

    ' get response
    Dim response As HttpWebResponse = DirectCast(request.GetResponse(), HttpWebResponse)
    Dim reader As StreamReader = New StreamReader(response.GetResponseStream())
    Dim responseContent As String = reader.ReadToEnd()

    ' dump raw response showing all fields for all NMIs
    Console.Write(responseContent + vbCrLf)
End Sub

Simple VB.NET code demonstrating a call to the SetSMS method. The example needs a TIM4biz call accounting messaging to succeed.

Imports System.IO
Imports System.Net

Private Async Sub ButtonSetSMS_Click(sender As Object, e As EventArgs) Handles ButtonSetSMS.Click
    Dim url As String = "https://api.tim4biz.com/api/settings/SetSMS"

    ' Create JSON content with UTF8 encoding
    Dim body As String = "{""number"": ""+61000000000"", ""message"": ""Hello from TIM4biz""}"
    Dim content As New StringContent(body, Encoding.UTF8, "application/json")

    ' convert bytes to string encoded as base 64 and add as header
    Dim plainTextBytes() As Byte = System.Text.Encoding.UTF8.GetBytes(TextBoxUser.Text + ":" + TextBoxPass.Text)
    Dim encode As String = System.Convert.ToBase64String(plainTextBytes)

    ' Send request and read response asynchronously
    Dim client As New HttpClient()
    client.DefaultRequestHeaders.Authorization =
        New Headers.AuthenticationHeaderValue("Basic", encode)
    Dim response As HttpResponseMessage = Await client.PostAsync(url, content)
    Console.WriteLine(Await response.Content.ReadAsStringAsync())
End Sub
06

API page not showing updates?

After an update to the main API page, you may need to force your browser to fetch the latest version. The usual Ctrl+F5 or Shift+⌘+R may not be enough. Follow these steps:

  1. 1
    Open the API homepage

    https://tim4biz.com/api/

  2. 2
    Click the JSON link at the top of the page

    https://tim4biz.com/api/swagger.json opens.

  3. 3
    Hard-refresh the swagger page

    Press Ctrl+F5 (or Shift+⌘+R) — the swagger.json page refreshes.

  4. 4
    Return to the main API page and hard-refresh

    Go back to https://tim4biz.com/api/ and press Ctrl+F5. The API page is finally refreshed.

07

API GET or POST

Each API heading indicates whether the call should be made via an HTTP GET or HTTP POST.

GET

Read without changing

Use GET to request information from TIM4biz without modifying any data.

POST

Insert, update or delete

Use POST to insert, update or delete remote data.

Heads up Using the incorrect request type will return a 400 Bad request response.

Need a hand?

Our team can enable API access, raise your rate limit and help you get the first sample running.