API Reference Version 1.0

Overview

The Buytasker API is a RESTful web service. The API exposes Logistics and related functions of the main Buytasker application and can be used for a variety of purposes such as creating Shipments, Tracking, WMS Orders, right through to extracting Accounting Data via our Network Pay Reports endpoint.

The Core Services API is designed to be easy to use and simple to test to help Buytasker's customers and partners get up and running quickly. Use the API endpoints to connect to Buytasker and other Integrated Service Providers, Dispatch and Track Shipments and retrieve required Shipping Documents.

Getting Started

The Buytasker API is a RESTful API. This means that the API is designed to allow you to work with objects using familiar HTTP verbs like so:

  • read = GET
  • create = POST
  • update = PUT
  • delete = DELETE

All production API requests are made to:

https://api.buytasker.com/api/1.0/

There is a testing sandbox to use when developing and testing applications, please contact support for credentials.

Tracking / Status

The following elements are returned in the Tracking Status response

result "success" or "failed" with corresponding message
code HTTP Response Code e.g. 200
data
date The message date in readable format.
location Name of current location.
message Additional information entered by carrier
status Current status of the delivery
person Person who has collected the delivery

Tracking / Embed

Use the HTML snippet to embed the Tracking Search widget on your website. HTML is inserted into your webpage and can be styled by applying your own CSS document.
DATA_TOKEN
Login to obtain your DATA_TOKEN here.

Logistics / Address Book

GET https://api.buytasker.com/api/1.0/addresses

Response

 {
    "result": "success",
    "code": 200,
    "data": {
        "addresses": [
            {
                "id": "696",
                "street_address": "152 City Rd ",
                "city": "London",
                "zip": "EC1V2NX",
                "country": "United Kingdom",
                "country_code": "GB",
                "phone": "+44320202222223",
                "user_id": "142",
                "active": "1",
                "lat": "51.5074",
                "long": "0.1278",
                "formatted_address": "101 Lane Street, London EC1V2NX, United Kingdom"
            }]
            
        } 

}

Get Address using ID

GET https://api.buytasker.com/api/1.0/addresses/696

Response

{
    "result": "success",
    "code": 200,
    "data": {
        "address": {
             "id": "696",
                "street_address": "152 City Rd ",
                "city": "London",
                "zip": "EC1V2NX",
                "country": "United Kingdom",
                "country_code": "GB",
                "phone": "+44320202222223",
                "user_id": "142",
                "active": "1",
                "lat": "51.5074",
                "long": "0.1278",
                "formatted_address": "101 Lane Street, London EC1V2NX, United Kingdom"
        }
    }
}

Add New Address

Request

POST https://api.buytasker.com/api/1.0/addresses/add
{address}
street_address
city
zip
country_id
see /countries endpoint for list of Country ID's
phone

Countries List

GET https://api.buytasker.com/api/1.0/countries

Response

			"countries": [
            {
                "id": "153",
                "name": "Netherlands",
                "code": "nl"
            }, ...
            

Logistics / Quote Request

Request Body

{quote}

project_title Your Project Title for your own reference.
carrier_type
Type
FCL Full Container Load.
FCX Full Container Consolidated.
PARCEL Courier Delivery.
LCL Less than a Container Load.
AIR Air Freight.
BB Break Bulk.
RORO Sea-Freight Roll on / Roll off.
SPECIAL Specialist Project and Niche.
Equipment
Quantity Number
FCL Container Types
20FTDVC
20ft DV Container ( 8\'6\' high )
40FTDSC
40ftDV Container ( 8\'6\' high )
40FTHCC
40ft HC Container ( 9\'6\' high )
45FTHC
45ft HC Container ( 9\'6\' high )
45FTHCPW
45ft HC PW Container ( 9\'6\' high ) Palletwide 2,5 mt
20FTRF
20ft RF Reefer Container ( + temp set )
40FTRF
40ft RF Reefer Container ( + temp set )
45FTRF
45ft RF Reefer Container ( + temp set )
20FTFR
20ft FR Flat Rack
40FTFR
40ft FR Flat Rack
20FTOT
20ft OT Open Top Container
40FTOT
40ft OT Open Top Container
20FTTC
20ft TC Tank Container (evtl with electric heating or steam heating )
20FTBC
20ft BC Bulk Container
pickup_id Address ID - Must be a valid Address in your Address Book.
pickup_ready_date Format YYYY-MM-DD H:M:S
delivery_id Address ID - Must be a valid Address in your Address Book.
delivery_date Format YYYY-MM-DD H:M:S
project_description Optional Project Description for your Reference.
pickup_incoterm Get /incoterms endpoint for Valid 2010 Incoterms.
delivery_incoterm Get /incoterms endpoint for Valid 2010 Incoterms.
pickup_notes Pickup Address Important Notes and Instructions.
delivery_notes Delivery Address Important Notes and Instructions.
expiry_days How long your RFQ should remain open before no more quotes can be received.
frequency Accepted values are 'One-off Shipment','Daily','Weekly','Fortnightly', 'Every 3 Weeks', 'Monthly', 'Quarterly', 'Half Yearly', 'Yearly', 'TBA', 'Not Sure'
frequency_quantity Number
strategy Project Strategy Value should be either 'Speed', 'Cost' or 'No Preference'
insurance Insurance type should be either 'Insurance Required', 'Insurance as Optional Extra' or 'No Insurance Required'
notes Important notes.
quote_throttle Number. Maximum 10 Quotes.
cargo
description Cargo details, name and type.
hs_code (optional)
weight Number.
weight_type 'KG','LBS'
volume Number.
volume_type 'CBM','CFT'
package_count Number.
package_type String, such as 'pallet','box'.
haz_code Hazardous Code for Dangerous Goods.

Example Response JSON

    {
    "result": "success",
    "code": 200,
    "data": {
        "quote_id": 1089,
        "quote_ref": "4-1089"
    }
}

FCL Equipment List

GET https://api.buytasker.com/api/1.0/equipment

Response

  			"equipment": {
            "20FTDVC": "20ft DV Container ( 8'6' high )",
            "40FTDSC": "40ftDV Container ( 8'6' high )",
            "40FTHCC": "40ft HC Container ( 9'6' high )",
            "45FTHC": "45ft HC Container ( 9'6' high )", 
            ...
  			

Incoterms List 2010

GET https://api.buytasker.com/api/1.0/incoterms

Response

			"incoterms": [
            {
                "FAS": "Free Alongside Ship (named port of shipment)"
            },
            {
                "FOB": "Free on Board (named port of shipment)"
            }, ...
            

Logistics / Rate Cards

Rate Cards List

GET https://api.buytasker.com/api/1.0/ratecards

Response

			"rate_cards": [
            {
                "customer_card_id": "59",
                "company_name": "Buytasker LTD ",
                "id": "59",
                "active": "1",
                "agent_id": "1554",
                "rate_card_id": "82",
                "customer_id": "1",
                "origin_country": "United Kingdom",
                "origin_country_code": "GB",
                "origin_zip": "",
                "origin_city": "",
                "carrier_type": "FCL",
                "destination_country": "Australia",
                "destination_country_code": "AU",
                "destination_zip": "",
                "destination_city": "",
                "trash": "0",
                "item_name": "Full Container Rates UK to AU",
                "expired": "0",
                "headers": "1",
                "expires": null,
                "published": "1"
            }, ...
            

Rate Card

GET https://api.buytasker.com/api/1.0/ratecards/59

Response

			
			"rate_card": {
            "rules": [
                {  ...
                
                

Logistics / Booking

Request Payload is identical to Quote Request


book/auto
Attempts to match 1 Active Rate Card rule and automatically make a booking.

POST https://api.buytasker.com/api/1.0/logistics/book/auto

book/{rate_card_id}
Instruct and match a Rate Card rule and make a booking.

POST https://api.buytasker.com/api/1.0/logistics/book/{rate_card_id}

Response

  				
  				{
  				
   				 "result": "success",
    			 "code": 200,
    			 "data": {
                 "project_id": 1090,
                 "booking_ref": "4-1090",
                 "tracking_id" : "1234"
    				
    				}
				}
  			
  			

Supported Data Format

The Buytasker API uses JSON as the default format.

Authentication

To use Buytasker's API, you'll need to Get your Authentication Token.

  1. Supply HTTP header: "X-TOKEN" value YOUR_API_KEY

Test Authentication Token

GET https://api.buytasker.com/api/1.0/test


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.buytasker.com/api/1.0/test",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "X-TOKEN: YOUR_API_KEY"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
} 

Tracking / Status

GET https://api.buytasker.com/api/1.0/tracking/status/TRACKING_NUMBER
{
  "result": "success",
  "data": [{
    "date": "Sun Jan 27 20:00:00 2019 +0400",
    "location": "DUBAI",
    "message": "",
    "status": "POD",
    "person": "Mr D Jones"
  }],
  "code": 200
}

Tracking / Embed


<script src="https://media.buytasker.com/api/tracking.js"></script>
<!DOCTYPE html> <html lang="en"> ... <div class="buytasker-tracking" data-api-version="1.0" data-token="DATA_TOKEN"> <h1><!-- Insert Custom Preloader Code --></h1> </div> ... </html>

Logistics / Address Book

GET https://api.buytasker.com/api/1.0/addresses
 $curl = curl_init();

  curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.buytasker.com/api/1.0/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "X-TOKEN: YOUR_API_KEY"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Query Address by ID

GET https://api.buytasker.com/api/1.0/addresses/ID

Add Address

POST https://api.buytasker.com/api/1.0/addresses/add
{ "address" : 

{

	"street_address" : "101 My Street",
	"city" : "Melbourne",
	"zip" : "3000",
	"country_id" : "12",
	"phone" : "+613939393939"

}

}
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.buytasker.com/api/1.0/addresses/add",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => POST_DATA,
  CURLOPT_HTTPHEADER => array(
    "X-TOKEN: YOUR_API_KEY"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Logistics / Quote Request

POST https://api.buytasker.com/api/1.0/logistics/quote/new

{
	"quote":
	{
			"project_title": "Test API",
			"carrier_type": {

				"type": "FCL",
				"equipment": [

					{
						"quantity": "1",
						"type": "20FTDVC"

					}

				]
			},
			"pickup_id": "100727",
			"pickup_ready_date": "now",
			"delivery_id": "100723",
			"delivery_date": "30 days",
			"project_description": "Testing API",
			"pickup_incoterm": "FOB",
			"delivery_incoterm": "DAP",
			"pickup_notes": "Please pickup",
			"delivery_notes": "Please deliver",
			"expiry_days": "30",
			"frequency": "One-off Shipment",
			"frequency_quantity": "1",
			"strategy": "speed",
			"insurance": "Insurance Required",
			"notes": "TESTING API",
			
			 			"quote_throttle": "5",
			"cargo": [

				{
					"description": "Pallet of chocolate",
					"hs_code": "NONE",
					"weight": "20",
					"weight_type": "KG",
					"volume": "1000",
					"volume_type": "CBM",
					"package_count": "20",
					"package_type": "Cardboard",
					"haz_code": ""
				},
				{
					"description": "Pallet of Oranges",
					"hs_code": "NONE",
					"weight": "50",
					"weight_type": "KG",
					"volume": "2000",
					"volume_type": "CBM",
					"package_count": "20",
					"package_type": "Pallets",
					"haz_code": ""
				}
			]


		}

}

Logistics / Rate Cards

GET https://api.buytasker.com/api/1.0/logistics/ratecards

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.buytasker.com/api/1.0/logistics/ratecards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "X-TOKEN: YOUR_API_KEY"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Logistics / Booking

  $curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.buytasker.com/api/1.0/logistics/book/auto",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>SAME_AS_QUOTE_PAYLOAD,
  CURLOPT_HTTPHEADER => array(
    "X-TOKEN: YOUR_API_KEY"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}