API requests are authenticated using the provided API public key, and a base64 encoded HMAC hash generated using the provided API private key.

When using a supported API Client class, the authentication values and headers are generated automatically.

The preferred method is to use a supported API Client class, and the below information is for reference only

Authentication Headers

The authentication details are to be sent as custom headers with the request as follows:

X-Public: {PUBLIC KEY}
X-Hash: {HMAC HASH}

Authentication Hash

The HMAC hash is generated using a sha256 hashed token; generated from the API public key and a date time stamp in the format YmdHi (YearMonthDayHourMinute e.g. 201501311430), and encoded using the API private key

The resulting token is to then be base64 encoded before sending

	$public_key = '1234567890';
	$private_key = '0987654321';

	$token = hash('sha256', $public_key . date('YmdHi'));
	$hash = base64_encode(hash_hmac('sha256', $token, $private_key));
										

	string public_key = '1234567890';
	string private_key = '0987654321';

	string datestamp = DateTime.Now.Year + DateTime.Now.Month.ToString().PadLeft(2, '0') + DateTime.Now.Day.ToString().PadLeft(2, '0') + DateTime.Now.Hour + DateTime.Now.Minute.ToString().PadLeft(2, '0');
	string token = public_key + datestamp;

	SHA256Managed hashString = new SHA256Managed();
	byte[] hash = hashString.ComputeHash(Encoding.UTF8.GetBytes(token));
	token = hash.Aggregate(string.Empty, (current, x) => current + String.Format("{0:x2}", x));


	using (var hMAC = new HMACSHA256(Encoding.UTF8.GetBytes(private_key)))
	{
	    hMAC.ComputeHash(Encoding.UTF8.GetBytes(token));
	    token = ByteToString(hMAC.Hash).ToLower();
	    token = System.Convert.ToBase64String(Encoding.UTF8.GetBytes(token));
	}
										

	import hmac, hashlib;
	import time;
	import base64;

	public_key = '501d132c35c885f9cd22f2adb424c212'
	private_key = 'a444588427e8cc348b675bda1743b547'
	the_time = time.strftime("%Y%m%d%H%M");

	crypt = hashlib.sha256(public_key + the_time);

	token = crypt.hexdigest();
	hash = base64.b64encode(hmac.new(private_key, token, hashlib.sha256).hexdigest());
										

NTP Server

As the authentication token is based off a datetime stamp, it is essential to ensure that the server making the request is in sync with the API time server.

Your server NTP should be configured to use the following address: ntp.tascomi.com

new APIClient();

The parameters to instantiate a new API Client class are as follows:

<?php
  // include APIClient class
  require_once 'class.APIClient.php';
  // instantiate request
  $request = new APIClient($public_key, $private_key, $request_uri, $request_method, $debug);
  // send request and get result
  $result = $request->sendRequest();
?>

The $result will be an array containing:

Usage Examples

View contact id 1 example

<?php
  // include APIClient class
  require_once 'class.APIClient.php';

  // setup request details
  $public_key = '1234567890';
  $private_key = '0987654321';
  $request_uri = 'https://hackney-planning.idoxcloud.com/rest/v1/contacts/1';

  // set appropriate request method to view
  $request_method = 'get';

  // instantiate request
  $request = new APIClient($public_key, $private_key, $request_uri, $request_method);
  
  // send request and get result
  $result = $request->sendRequest();

  // show response
  print_r($result);
?>

Array
(
    [header] => Array
        (
            [0] => HTTP/1.1 200 OK
            [1] => Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
            [2] => Pragma: no-cache
            [3] => Vary: Accept-Encoding,User-Agent
            [4] => Content-Type: application/json
        )

    [http_status] => 200 - OK
    [reply] => stdClass Object
        (
            [id] => 1
            [title_id] => 2
            [firstname] => John
            [surname] => Doe
            [house_name_or_number] => Apt 12
            [postcode] => ZY12 3XY
            [email] => john.doe@example.com
        )
)

View all contacts, order by firstname example

<?php
  // include APIClient class
  require_once 'class.APIClient.php';

  // setup request details
  $public_key = '1234567890';
  $private_key = '0987654321';
  $request_uri = 'https://hackney-planning.idoxcloud.com/rest/v1/contacts';

  // set appropriate request method to view
  $request_method = 'get';

  // set optional parameter to sort results
  $request_data = array(
    'sort'=>'firstname'
  );

  // instantiate request
  $request = new APIClient($public_key, $private_key, $request_uri, $request_method);
  
  // send request and get result
  $result = $request->sendRequest();

  // show response
  print_r($result);
?>

Array
(
    [header] => Array
        (
            [0] => HTTP/1.1 200 OK
            [1] => Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
            [2] => Pragma: no-cache
            [3] => Vary: Accept-Encoding,User-Agent
            [4] => Content-Type: application/json
            [5] => X-Number-Of-Results: 2
            [6] => X-Page-Number: 1
            [7] => X-Results-Per-Page: 30
        )

    [http_status] => 200 - OK
    [number_of_results] => 2
    [page_number] => 1
    [results_per_page] => 30
    [reply] => Array
        (
            [0] => stdClass Object
                (
                    [id] => 1
                    [title_id] => 2
                    [firstname] => John
                    [surname] => Doe
                    [house_name_or_number] => Apt 12
                    [postcode] => ZY12 3XY
                    [email] => john.doe@example.com
                )

            [1] => stdClass Object
                (
                    [id] => 2
                    [title_id] => 3
                    [firstname] => Jane
                    [surname] => Doe
                    [house_name_or_number] => 35a
                    [postcode] => EX12 3XZ
                    [email] => jane.doe@example.com
                )
        )
)

Search contacts, firstname Sam example

<?php
  // include APIClient class
  require_once 'class.APIClient.php';

  // setup request details
  $public_key = '1234567890';
  $private_key = '0987654321';
  $request_uri = 'https://hackney-planning.idoxcloud.com/rest/v1/contacts';

  // set appropriate request method to search
  $request_method = 'get';

  // set parameters for search
  $request_data = array(
    'firstname'=>'Sam',
    'sort'=>'surname'
  );

  // instantiate request
  $request = new APIClient($public_key, $private_key, $request_uri, $request_method, $request_data);
  
  // send request and get result
  $result = $request->sendRequest();

  // show response
  print_r($result);
?>

Array
(
    [header] => Array
        (
            [0] => HTTP/1.1 200 OK
            [1] => Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
            [2] => Pragma: no-cache
            [3] => Vary: Accept-Encoding,User-Agent
            [4] => Content-Type: application/json
            [5] => X-Number-Of-Results: 1
            [6] => X-Page-Number: 1
            [7] => X-Results-Per-Page: 30
        )

    [http_status] => 200 - OK
    [number_of_results] => 1
    [page_number] => 1
    [results_per_page] => 30
    [reply] => Array
        (
            [0] => stdClass Object
                (
                    [id] => 3
                    [title_id] =>
                    [firstname] => Sam
                    [surname] => Doe
                    [house_name_or_number] =>
                    [postcode] =>
                    [email] => sam.doe@example.com
                )
        )
)

Create contact example

<?php
  // include APIClient class
  require_once 'class.APIClient.php';

  // setup request details
  $public_key = '1234567890';
  $private_key = '0987654321';
  $request_uri = 'https://hackney-planning.idoxcloud.com/rest/v1/contacts';

  // set appropriate request method to create
  $request_method = 'put';

  // set parameters for contact data
  $request_data = array(
    'firstname'=>'James',
    'surname'=>'Doe',
    'house_name_or_number'=>'41'
  );

  // instantiate request
  $request = new APIClient($public_key, $private_key, $request_uri, $request_method, $request_data);
  
  // send request and get result
  $result = $request->sendRequest();

  // show response
  print_r($result);
?>

Array
(
    [header] => Array
        (
            [0] => HTTP/1.1 200 OK
            [1] => Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
            [2] => Pragma: no-cache
            [3] => Vary: Accept-Encoding,User-Agent
            [4] => Content-Type: application/json
        )

    [http_status] => 200 - OK
    [reply] => stdClass Object
        (
            [id] => 4
            [title_id] =>
            [firstname] => James
            [surname] => Doe
            [house_name_or_number] => 41
            [postcode] =>
            [email] =>
        )
)

Update contact example

<?php
  // include APIClient class
  require_once 'class.APIClient.php';

  // setup request details
  $public_key = '1234567890';
  $private_key = '0987654321';
  $request_uri = 'https://hackney-planning.idoxcloud.com/rest/v1/contacts/4';

  // set appropriate request method to update
  $request_method = 'post';

  // set parameters for contact data
  $request_data = array(
    'email'=>'james.doe@example.com',
    'postcode'=>'JD12 3LR',
  );

  // instantiate request
  $request = new APIClient($public_key, $private_key, $request_uri, $request_method, $request_data);
  
  // send request and get result
  $result = $request->sendRequest();

  // show response
  print_r($result);
?>

Array
(
    [header] => Array
        (
            [0] => HTTP/1.1 200 OK
            [1] => Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
            [2] => Pragma: no-cache
            [3] => Vary: Accept-Encoding,User-Agent
            [4] => Content-Type: application/json
        )

    [http_status] => 200 - OK
    [reply] => stdClass Object
        (
            [id] => 4
            [title_id] =>
            [firstname] => James
            [surname] => Doe
            [house_name_or_number] => 41
            [postcode] => JD12 3LR
            [email] => james.doe@example.com
        )
)

Delete contact example

<?php
  // include APIClient class
  require_once 'class.APIClient.php';

  // setup request details
  $public_key = '1234567890';
  $private_key = '0987654321';
  $request_uri = 'https://hackney-planning.idoxcloud.com/rest/v1/contacts/4';

  // set appropriate request method to delete
  $request_method = 'delete';

  // instantiate request
  $request = new APIClient($public_key, $private_key, $request_uri, $request_method);
  
  // send request and get result
  $result = $request->sendRequest();

  // show response
  print_r($result);
?>

Array
(
    [header] => Array
        (
            [0] => HTTP/1.1 200 OK
            [1] => Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
            [2] => Pragma: no-cache
            [3] => Vary: Accept-Encoding,User-Agent
            [4] => Content-Type: application/json
        )

    [http_status] => 200 - OK
    [reply] =>
)

Upload files to Uploaded Files section:

Please make sure you are using latest version of class.APIClient.php

<?php
// include APIClient class
require_once 'class.APIClient.php';

// setup request details
$public_key = '1234567890';
$private_key = '0987654321';
$request_uri = 'https://hackney-planning.idoxcloud.com/rest/v1/licences/4';

// set appropriate request method to update
$request_method = 'post';

// set parameters for contact data
$request_data = array(
'email'=>'james.doe@example.com',
'postcode'=>'JD12 3LR',
// you can put here one or multiple files, but files key must be an array
'files'=>[

// FULL_PATH_TO_THE_FILES should present a full path to thel local file, for instance:
// Windows: @C:\Users\Documents\file.pdf 
// MAC: @/Users/USER_NAME/Documents/file.pdf

'@'. FULL_PATH_TO_THE_FILES . 'file.pdf', 
'@'. FULL_PATH_TO_THE_FILES . 'file2.png'


],
// optional just to present nicely on the system Uploaded Files Section
'folder_name'=>'--- any folder name ---' 
);

// instantiate request
$request = new APIClient($public_key, $private_key, $request_uri, $request_method, $request_data);

// send request and get result
$result = $request->sendRequest();

// show response
print_r($result);
?>

Array
(
[header] => Array
	(
		[0] => HTTP/1.1 200 OK
		[1] => Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
		[2] => Pragma: no-cache
		[3] => Vary: Accept-Encoding,User-Agent
		[4] => Content-Type: application/json
	)

[http_status] => 200 - OK
[reply] => stdClass Object
	(
		[id] => 4
		[title_id] =>
		[firstname] => James
		[surname] => Doe
		[house_name_or_number] => 41
		[postcode] => JD12 3LR
		[email] => james.doe@example.com
		[uploaded_files] => Array
		(
			[0] => stdClass Object
				(
					[id] => 269
					[title] => file.pdf
					[name] => 1660043487::-::file.pdf
					[size] => 8373
					[custom_date] => 2022-08-01
					[file] => file.pdf
					[error] => 
				)

			[1] => stdClass Object
				(
					[id] => 270
					[title] => file2.png
					[name] => 1660043487::-::file2.png
					[size] => 555657
					[custom_date] => 2022-08-01
					[file] => file2.png
					[error] => 
				)

		)

	)
	)
)

Upload file(s) to directly to table(s):

Please make sure you are using latest version of class.APIClient.php

<?php
// include APIClient class
require_once 'class.APIClient.php';

// setup request details
$public_key = '1234567890';
$private_key = '0987654321';
$request_uri = 'https://hackney-planning.idoxcloud.com/rest/v1/licences/4';

// set appropriate request method to update
$request_method = 'post';

// set parameters for contact data
$request_data = array(
'email'=>'james.doe@example.com',
'postcode'=>'JD12 3LR',
// you can put here one or multiple files, but files key must be an array
'plans'=>'@'. FULL_PATH_TO_THE_FILES . 'file2.png',

// FULL_PATH_TO_THE_FILES should present a full path to thel local file, for instance:
// Windows: @C:\Users\Documents\file.pdf 
// MAC: @/Users/USER_NAME/Documents/file.pdf

);

// instantiate request
$request = new APIClient($public_key, $private_key, $request_uri, $request_method, $request_data);

// send request and get result
$result = $request->sendRequest();

// show response
print_r($result);
?>

List of allowed tables and columns to upload file(s):