Developer Portal
API Documentation
Webhook Documentation

Getting Started with the TechLink API

The TechLink Services API uses a number of standard technologies, patterns, and pratices for its implementation. These are described in somewhat broad strokes below, or in detailed form in the API Documentation.

Best Practices

If you are interested in integrating your business systems with TechLink Services, here are some ways to get started.

  • Familiarize yourself with TechLink's work flow and business entity relationships (work orders, job sites, user accounts, and so on).
  • Identify parallels with your own business practices, design integration points into your own existing UI, and add customized elements and flow steps in order to take advantage of the TechLink API and lessen your manual workload.
  • If desired, TechLink Solutions can provide custom integration for your systems.

RESTful APIs

The TechLink Services API uses RESTful architecture for its web service implementation.

You are probably familiar with the REST pattern, but if you need more information, there are a plethora of definitions, tutorials, and examples out there on the web. For a dry, academic breakdown, there's always Wikipedia, but for more intuitive, differently-scoped, sometimes brilliant, sometimes goofy information, ask Google.

The TechLink Services Work Flow

The TechLink Services work flow centers around the work order, a document detailing work to be performed for a client by an installer with their technicians. These work orders can be created via the API, once some prerequisites have been fulfilled.

The work order will need a (job) site, a location where the work will be performed. This site can have contacts, documents, and generic attributes associated with it.

The work order can have certain user accounts associated with it in key roles (submitter, etc). The work order can also have specific tasks, documents, notes, and more associated with it. Requirements can be set on the work order for completion - job site photographs and close-out documents for the installer to submit.

So, in general, the steps are:

  • sign up for TechLink Services user accounts for your key personnel
  • create a job site with address and contact details
  • create a work order with any associated users, requirements, and detailed instructions on the work to be performed
  • relax and let TechLink Services guide the work to completion, keeping you up-to-date and informed every step of the way

Integration Examples

PHP

This page contains some examples of accessing and working with the TechLink API from various programming languages. Note that PHP and curl samples also exist on the API documentation page.

Authentication and Retrieving a Work Order in PHP

The TechLink API authentication protocol is described in detail on the API documentation page. Below is a sample API call function written in PHP. The TechLink API can be accessed using entirely native PHP functions.

<?php /* * This function can handle accessing the API through the POST, GET, or DELETE methods. * */ function api_call($endpoint, $args = [ ], $request_type = 'GET') { global $api_url; global $user; global $password; $url = $api_url . $endpoint; $time = empty($args['time']) ? time() : $args['time']; if(isset($args['time'])) unset($args['time']); $curl = curl_init(); if($request_type == 'GET' || $request_type == 'DELETE') if($args && count($args)) { $argstring = http_build_query($args); if(!empty($argstring)) $url .= '?' . $argstring; } $options = array( CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => 1, CURLOPT_SSL_VERIFYHOST => false, CURLOPT_SSL_VERIFYPEER => false, CURLOPT_HTTPHEADER => [ 'X-Authorization: ' . $user . ':' . md5($password) ] ); if($request_type == 'POST' || $request_type == 'FILE') { $options[CURLOPT_POST] = 1; if($args && count($args)) $options[CURLOPT_POSTFIELDS] = $request_type == 'FILE' ? $args : http_build_query($args); } else if($request_type == 'DELETE') { $options[CURLOPT_CUSTOMREQUEST] = 'DELETE'; if($args && count($args)) $options[CURLOPT_POSTFIELDS] = http_build_query($args); } curl_setopt_array($curl, $options); if(!($output = curl_exec($curl))) print("Fatal error: Curl did not return output; error: " . curl_error($curl) . "<br>"); curl_close($curl); $decoded_output = json_decode($output); return($decoded_output); } function get_workorder($id) { return api_call("workorder/$id", [ "include_notes" => true ]); } print("<pre>"); var_dump(get_workorder(12345)); print("</pre>"); ?>

A typical response to the above code follows:

object(stdClass)#13 (4) { ["code"]=> int(200) ["message"]=> string(23) "Work order #12345 found" ["data"]=> object(stdClass)#12 (1) { ["workorder"]=> object(stdClass)#29 (16) { ["id"]=> int(12345) ["status"]=> string(9) "Created" ["status_code"]=> int(10) ["type"]=> string(9) "Workorder" ["submitter_id"]=> int(1179) ["po"]=> string(11) "Purchase Order #321" ["summary"]=> string(23) "Service Call - Bend OR" ["description"]=> string(50) " This is the detailed description of work that should be done... " ["requested_time"]=> string(10) "4/16 10am" ["scheduled_date"]=> string(19) "2018-04-16 10:00:00" ["site_id"]=> int(54321) ["installer"]=> object(stdClass)#19 (3) { ["name"]=> string(22) "Installer Person" ["phone"]=> string(12) "123-456-7890" ["email"]=> string(23) "demo@notreal.com" } ["planned_tech"]=> object(stdClass)#17 (2) { ["name"]=> string(0) "" ["phone"]=> string(0) "" } ["notes"]=> array(1) { [0]=> object(stdClass)#120 (5) { ["note_id"]=> int(123456) ["workorder_id"]=> int(12345) ["author"]=> string(13) "Joseph Blow" ["content"]=> string(29) "Status set to Created." ["created_date"]=> string(23) "2018-04-15 08:01:16 EDT" } } ["url"]=> string(77) "https://portal.techlinksvc.net/portal/index.php?sp=orders&act=detail&id=12345" ["created_date"]=> string(23) "2018-04-15 08:01:15 EDT" ["last_modified"]=> string(23) "2018-04-16 15:01:51 UTC" } } ["time"]=> float(0.0840711593628) }

JavaScript

The TechLink API can be accessed via JavaScript if an md5() encryption support function/library is included. There are plenty of JavaScript md5() implementations to choose from; use the one that best suits your needs.

Authentication and Creating a Site in JavaScript

Note that the following API access function assumes that an external md5() encryption function has been provided.

<script type='text/javascript'> [abstract function md5() { ... }] /* * This is not a very fleshed-out example, but demonstrates the authentication and creation of a site. * */ function api_call(endpoint, args) { var url = api_url + endpoint; var xhttp = new XMLHttpRequest(); xhttp.open('POST', url, false); xhttp.setRequestHeader("X-Authorization", user + ':' + md5(password)); if(args) { args = JSON.stringify(args); xhttp.setRequestHeader("Content-type", "application/json; charset=utf-8"); } xhttp.send(args); var response = JSON.parse(xhttp.responseText); return response; } console.log(api_call('site', { 'primary_contact_name': 'firstyfirst mccontact', 'primary_contact_phone': '111-1111', 'primary_contact_email': 'primary@1.com', 'secondary_contact_name': 'secondy mcsecond', 'secondary_contact_phone': '222-2222', 'secondary_contact_email': 'secondary@2.com', 'name': 'api site', 'address1': '321 main street', 'city': 'new york', 'state': 'ny', 'zip': '10021', 'phone': '123-3214', 'fax': 'who faxes?', 'site_id': 'siteymcID', 'notes': "These are notes for the site", 'enable_notifications': '329, 781', 'additional_notifications': 'test@test.com,test123@test.com', })); </script>

A typical response to the above code follows:

object(stdClass)#13 (4) { ["code"]=> int(200) ["message"]=> string(23) "Site #54321 successfully created" ["data"]=> object(stdClass)#12 (13) { ["id"]=> int(54321) ["name"]=> string(22) "Out In The Wilderness" ["siteid"]=> string(3) "Store #1234" ["phone"]=> string(12) "212-867-5309" ["fax"]=> string(0) "" ["address"]=> object(stdClass)#29 (11) { ["street"]=> string(22) "1 Main Street" ["street2"]=> string(0) "" ["street3"]=> string(0) "" ["city"]=> string(7) "Lincoln" ["state"]=> string(8) "Nebraska" ["state_abbr"]=> string(2) "NE" ["zip"]=> string(5) "68516" ["country"]=> string(3) "USA" ["latitude"]=> string(9) "40.716281" ["longitude"]=> string(10) "-96.678337" ["timezone"]=> string(15) "America/Chicago" } ["contact1"]=> object(stdClass)#19 (3) { ["name"]=> string(12) "Jonathan Doe" ["phone"]=> string(12) "212-122-2111" ["email"]=> string(3) "jdoe@notreal.com" } ["contact2"]=> object(stdClass)#17 (3) { ["name"]=> string(0) "" ["phone"]=> string(0) "" ["email"]=> string(0) "" } ["notes"]=> string(0) "" ["attributes"]=> array(0) { } ["url"]=> string(76) "https://portal.techlinksvc.net/portal/index.php?sp=sites&act=detail&id=54321" ["created_date"]=> string(23) "2018-10-11 14:18:11 EDT" ["last_modified"]=> string(23) "2018-10-11 16:19:14 UTC" } } ["time"]=> float(0.0840711593628) }