NAV Navbar
Logo

Introduction

Welcome to the FreightExchange API. These APIs will allow you to connect your own systems to FreightExchange to carry out a number of different functions.

We’re busy building more APIs at the moment and this page will be regularly updated as we make them available so please come back here regularly. We also want to hear from you about the interfaces you would find useful and ways we can make any of the APIs easier to work with.

To receive updates on our APIs either create an API key via the company profile page in FreightExchange, or enter your details below. Either way we’ll only send you information about our APIs, nothing else.

Authentication

We will issue you with a token which identifies your organisation. These token must be included in every call to our APIs

securityToken: xxxxxxxxxxxxxxxxxx

We will issue separate tokens for our development and live environments. Please contact us to obtain the tokens.

Quote (Version 1)

Get A Quote

Example request

{
    "pickupDate" : "2016-10-12",
    "originSuburb" : "SYDNEY",
    "originState" : "NSW",
    "originPostCode" : "2000",
    "originCountryCode" : "AU",
    "originResidential" : false,
    "destinationSuburb" : "MELBOURNE",
    "destinationState" : "VIC",
    "destinationPostCode" : "3000",
    "destinationCountryCode" : "AU",
    "destinationResidential" : false,
    "freightType" : "PALLETS",
    "tailLiftPickup" : false,
    "tailLiftDelivery" : false,
    "securityToken" : "XXXXXX",
    "insuranceValue" : 250,
    "resultOutput" : "FULL",
    "items" : [
        {
            "length" : 1.2,
            "width" : 1.2,
            "height" : 1.2,
            "weight" : 400,
            "quantity" : 1
        }
        ]
}

Example response

{
  "success": true,
  "quoteId": 4525,
  "insuredValue": 250,
  "priceResult": [
    {
      "priceId": 120596,
      "freightPrice": 179.08,
      "insurancePrice": 3.5,
      "consignmentFee": 0,
      "netPrice": 182.58,
      "gst": 18.26,
      "grossPrice": 200.84,
      "priceType": "FE",
      "minTransitTime": 2,
      "maxTransitTime": 2
    },
    {
      "priceId": 120597,
      "freightPrice": 189.46,
      "insurancePrice": 3.5,
      "consignmentFee": 0,
      "netPrice": 182.58,
      "gst": 18.26,
      "grossPrice": 200.84,
      "priceType": "FE",
      "minTransitTime": 1,
      "maxTransitTime": 1
    }
  ]
}

This endpoint is used to obtain a quote from FreightExchange. You must provide basic details of the shipment including the origin, destination, weight and dimensions. It is essential that you provide correct and complete information when calling this API as otherwise the price we provide will not be accurate. Freight pricing is totally dependent on origin, destination, weight and dimensions so if the actual shipment is different to the one you got a quote for, extra charges will apply.

HTTP Request

This endpoint will only accept POST requests.

Dev https://apidemo.freightexchange.com.au/api/quote

Live https://api.freightexchange.com.au/quote

Input Parameters

Parameter Type Mandatory Description
pickupDate date Y Intended pick-up date for the shipment. See notes below regarding pick-up dates.
originSuburb text Y Origin suburb
originState text N Origin state - use the standard abbreviation (e.g. NSW, VIC)
originPostCode text Y Origin post code
originCountryCode text Y Origin country - use standard ISO country codes (e.g. AU)
originResidential boolean Y Indicates if the origin address is residential
destinationSuburb text Y Destination suburb
destinationState text N Destination state - use the standard abbreviation (e.g. NSW, VIC)
destinationPostCode text Y Destination post code
destinationCountryCode text Y Destination country - use standard ISO country codes (e.g. AU)
destinationResidential boolean Y Indicates if the destination address is residential
freightType text Y The type of freight being shipped. Possible values are PALLETS or OTHER
tailLiftPickup boolean Y Indicates if a tail lift vehicle is required for pick-up
tailLiftDelivery boolean Y Indicates if a tail lift vehicle is required for delivery
securityToken text Y Your secuirty token
insuranceValue number Y The amount of insurance cover you require for the shipment. If no cover is required send 0.
resultOutput text Y The type of result output required. SINGLE will cause only the lowest price to be returned, whilst FULL will return all available prices and services
useSpecifiedPickupDate boolean N If you specify true the pickupDate you supply will be used for the quote. If you do not include this parameter or specify false the quote will use the next working day at the origin location. For example if the pickupDate you specify is a Saturday the quote will use Monday’s date.
items Y Array of the items being shipped. See the table below for full details

You must specifiy one or more items in the input using the parameters below:

Parameter Type Mandatory Description
length double Y The length of the item in metres
width double Y The width of the item in metres
height double Y The height of the item in metres
weight double Y The item weight of the items in kilograms
quantity number Y The number of these items being shipped

Validation Rules

Pick-up Dates

As many of our carriers do not work weekends, you will typically get either very expensive or no quotes if you specify a weekend or public holiday for pick-up. By default the API will therefore automatically provide prices for the next working day at the origin location unless you include useSpecifiedPickupDate : true in your request. In most use cases you will not want to include this value - if you do have a requirement for regular weekend pick-ups please contact us to discuss this further.

Response Parameters

Parameter Type Description
success boolean Indicates if the request was successful
quoteId number Unique identifier for this quote
insuredValue double Confirms the value being insuredValue
priceResult Array of prices

The priceResult element will contain one of more prices with the following parameters:

Parameter Type Description
priceId number Unique identifier for this price
freightPrice double The total price for the freight including surcharges
insurancePrice double The price for the requested insurance cover
consignmentFee double This parameter is included for future use
netPrice double The net price for the shipment including freight and insurance
gst double The amount of GST applicable to this price
grossPrice double The gross price for this shipment
priceType text Indicates where this price is for a FreightExchange carrier (FE) or one of your connected carriers (“)
minTransitTime number The minimum expected transit time in working days
maxTransitTime number The maximum expected transit time in working days

Book - Coming Soon

Introduction

Our booking endpoint allows you to make a freight booking with FreightExchange. There’s a couple of different ways this can work so you should read the documentation below and consider which is the most appropriate for your use case. This might not be an IT or technical decision but will have to fit in with how your business operates. At the highest level there are two approaches to booking a shipment via our API:

We realise the second option is convenient but somewhat limited at this stage and we will be making this better soon.

Once you’ve decided which is the best option for your business please read on so you can also understand how we send you shipping labels as you also have a few options to consider.

Confirmation and labelling

When you make a booking with FreightExchange, we have to pass the consignment details to our carriers in order to confirm the booking. Unfortunately some of our carriers’ system take longer to process these messages than we would like which can lead to the process taking a while to complete. We understand that this may not be acceptable to your own systems so we give you the option of confirming a booking with FreightExchange without waiting for the details to be passed to the carrier. Selecting this option reduces the overall API response time but means that you won’t receive shipping labels in our response. Instead we will send the labels to you via email, by calling a webhook that you provide, upload them to FreightExchange or you can poll our system until they are available. Again the choice you make here will be driven as much by how your business and systems operate as technical considerations.

Testing

Unlike our quoting API you will need to take care when testing our booking API. Successful calls to this API will result in a booking being made with FreightExchange and also our carriers - these will normally also be charged to your account. We therefore strongly encourage you to carry out extensive testing via our development API which will ensure that live bookings are not made.

Booking after getting a quote

HTTP Request

This endpoint will only accept POST requests.

Dev https://apidemo.freightexchange.com.au/api/v2/book

Live https://api.freightexchange.com.au/v2/book

In this scenario you will first obtain a quote using the quote API described above. You will then use the results from that API to make a confirmed booking. To do this you must record the quoteId and, if you want to book a specific price, priceId returned by the quote API. Depending on the information you provided to the quote API you may have to provide additional address information.

Example request - waiting for booking to be confirmed with carrier

{
    "securityToken": "XXXXXXXXXXXXX",
    "quoteId": 11564,
    "freightDescription": "test freight",
    "waitForConfirmation": true
}   

Example request - not waiting for booking to be confirmed, labels sent by email

{
    "securityToken": "XXXXXXXXXXXXX",
    "quoteId": 11564,
    "freightDescription": "test freight",
    "waitForConfirmation": false,
  "labelDeliveryMethod" : "EMAIL",
  "labelDeliveryEmail" : "labels@test.com"
}   

Input parameters

Parameter Type Mandatory Description
securityToken text Y Your security token.
quoteId number Y The quoteId returned from the quote API that you wish to book/
priceId number N If you wish to book a specific price result returned from the quote API then you must specify the returned priceId value. If this field is ommitted then we will book the cheapest price for the specified quote.
freightDescription text N A description of the freight you are sending.
costCentre text N The cost centre to be used for this booking. If you don’t have cost centres set up on your account this cannot be used.
shipperReference text N Your reference for this shipment which will be shown on our invoice.
originCompanyName text Y* Name of the origin company.
originContactName text Y* Contact name at the origin.
originPhoneNumber text Y* Phone number for origin contact.
originEmail text N Email address for origin contact.
originUnit text N Unit number for origin address.
originNumber text Y* Street number for origin address.
originStreet text Y* Street name for origin address.
originOpeningTime time Y* Time that the origin location opens - HH:mm format.
originClosingTime time Y* Time that the origin location closes - HH:mm format.
pickupInstructions text N Any instructions to be passed to the collecting driver.
destinationCompanyName text Y* Name of the destination company.
destinationContactName text Y* Contact name at destination.
destinationPhoneNumber text Y* Phone number for destination contact.
destinationEmail text N Email address for destination contact.
destinationUnit text N Unit number for destination address.
destinationNumber text Y* Street number for destination address.
destinationStreet text Y* Street name for destination address.
destinationOpeningTime time Y* Time that the destination location opens - HH:mm format.
destinationClosingTime time Y* Time that the destination location closes - HH:mm format.
deliveryInstructions text N Any instructions to be passed to the delivering driver.
waitForConfirmation boolean Y Indicates whether you wish to wait for FreightExchange to confirm the booking with our carrier before responding. See notes above for more information.
labelDeliveryMethod text Y How you want shipping labels to be delivered. Valid values are EMAIL, WEBHOOK, NONE. See below for further information.
labelDeliveryEmail text N Email address that shipping labels should be sent to. This is only valid if labelDeliveryMethod = EMAIL and if ommitted will default to the primary user on your account.
labelDeliveryWebhook text N URL we should call to delivery labels. Required if labelDeliveryMethod = WEBHOOK.

Fields marked as Y* in the mandatory can be included in either the quote API call or the booking API call. If they are provided in both then those supplied in the booking API call will be used.

Response parameters

Example response - waiting for booking to be confirmed

{
    "jobId": 4591,
    "trackingNumber": "7069160000171",
    "carrierName": "Toll IPEC",
    "serviceName": "TOLL_IPEC_ROAD_EXPRESS",
    "expectedDeliveryDate": "2017-08-15 00:00:00",
    "shippingLabelUrl": "https://demo.freightexchange.com.au/secure/getJobAttachment?jobId=4591&fileId=2906&download=true"
}

Example response - not waiting for booking to be confirmed

{
    "jobId": 4592,
    "carrierName": "Toll IPEC",
    "serviceName": "TOLL_IPEC_ROAD_EXPRESS",
    "expectedDeliveryDate": "2017-08-15 00:00:00"
}
Parameter Type Description
jobId number FreightExchange booking number
errorMessage text Any error message relating to your request
errorNumber number Error number. See below for further details.
trackingNumber text Carrier’s tracking number
carrierName text Name of the carrier who will handle the shipment.
serviceName text Name of the carrier’s service.
pickupDate date Expected pick-up date.
expectedDeliveryDate data Expected delivery date.
shippingLabelUrl text URL to download shipping labels.
shippingDocs base64 Base 64 representation of the shipping labels in PDF format.

Booking without a quote

HTTP Request

This endpoint will only accept POST requests.

Dev https://apidemo.freightexchange.com.au/api/v2/book/direct

Live https://api.freightexchange.com.au/v2/book/direct

This alternative method of making a booking allows you to book a shipment without first obtaining a quote. Whilst this only requires a single call to our APIs and is therefore somewhat simpler to implement it does, of course, have its drawbacks. Where you consistently ship similar items and therefore have a developed knowledge of freight costs this might be an appropriate method. However if you ship large or irregular items, or ship to regional or remote destinations we strongly recommend that you always obtain a quote first.

The call to this API is effectively a combination of the quote and book structures detailed above.

Example request - waiting for confirmation

//Sample

Input parameters

Parameter Type Mandatory Description
securityToken text Y Your security token
originCompanyName text Y Name of the origin company.
originContactName text Y Contact name at the origin.
originPhoneNumber text Y Phone number for origin contact.
originEmail text N Email address for origin contact.
originUnit text N Unit number for origin address.
originNumber text Y Street number for origin address.
originStreet text Y Street name for origin address.
originSuburb text Y Suburb for origin address.
originState text N State for origin address.
originPostCode text Y Post code for origin address.
originCountryCode text Y Origin country code - must be a valid 2-character ISO country code.
originOpeningTime time Y Time that the origin location opens - HH:mm format.
originClosingTime time Y Time that the origin location closes - HH:mm format.
originResidential boolean Y Indicates if the origin address is residential
pickupInstructions text N Any instructions to be passed to the collecting driver.
destinationCompanyName text Y Name of the destination company.
destinationContactName text Y Contact name at destination.
destinationPhoneNumber text Y* Phone number for destination contact.
destinationEmail text N Email address for destination contact.
destinationUnit text N Unit number for destination address.
destinationNumber text Y Street number for destination address.
destinationStreet text Y Street name for destination address.
destinationSuburb text Y Suburb for destination address.
destinationState text N State for destination address.
destinationPostCode text Y Post code for destination address.
destinationCountryCode text Y Destination country code - must be a valid 2-character ISO country code.
destinationOpeningTime time Y Time that the destination location opens - HH:mm format.
destinationClosingTime time Y Time that the destination location closes - HH:mm format.
destinationResidential boolean Y Indicates if the destination address is residential
deliveryInstructions text N Any instructions to be passed to the delivering driver.
freightDescription text N A description of the freight you are sending.
costCentre text N The cost centre to be used for this booking. If you don’t have cost centres set up on your account this cannot be used.
shipperReference text N Your reference for this shipment which will be shown on our invoice.
items Y Array of the items being shipped. See the table below for full details
pickupDate date Y Intended pick-up date for the shipment. See notes below regarding pick-up dates.
insuranceValue number Y The amount of insurance cover you require for the shipment. If no cover is required send 0.
selectCheapest boolean Y If true we will select the cheapest price for your shipment and book it. If false you must specify a carrierId and serviceId to indicate which carrier to book - if you want to specify carriers please contact us for assistance.
carrierId number N Specifies the carrier to book for this shipment. Please contact us for assistance if you want to use this option.
serviceId number N Specifies the carrier service to book for this shipment. Please contact us for assistance if you want to use this option.
waitForConfirmation boolean Y Indicates whether you wish to wait for FreightExchange to confirm the booking with our carrier before responding. See notes above for more information.
labelDeliveryMethod text Y How you want shipping labels to be delivered. Valid values are EMAIL, WEBHOOK, NONE. See below for further information.
labelDeliveryEmail text N Email address that shipping labels should be sent to. This is only valid if labelDeliveryMethod = EMAIL and if ommitted will default to the primary user on your account.
labelDeliveryWebhook text N URL we should call to delivery labels. Required if labelDeliveryMethod = WEBHOOK.

boolean originResidential boolean destinationResidential

Pick-up Dates

As many of our carriers do not work weekends, you will typically get either very expensive or no quotes if you specify a weekend or public holiday for pick-up. By default the API will therefore automatically provide prices for the next working day at the origin location unless you include useSpecifiedPickupDate : true in your request. In most use cases you will not want to include this value - if you do have a requirement for regular weekend pick-ups please contact us to discuss this further.

Items

You must specifiy one or more items in the input using the parameters below:

Parameter Type Mandatory Description
length double Y The length of the item in metres
width double Y The width of the item in metres
height double Y The height of the item in metres
weight double Y The item weight of the items in kilograms
quantity number Y The number of these items being shipped

Example response - waiting for booking to be confirmed

Response parameters

Parameter Type Description
jobId number FreightExchange booking number
errorMessage text Any error message relating to your request
errorNumber number Error number. See below for further details.
trackingNumber text Carrier’s tracking number
carrierName text Name of the carrier who will handle the shipment.
serviceName text Name of the carrier’s service.
pickupDate date Expected pick-up date.
expectedDeliveryDate data Expected delivery date.
shippingLabelUrl text URL to download shipping labels.
shippingDocs base64 Base 64 representation of the shipping labels in PDF format.

Webhooks

Booking confirmation

Introduction

This webhook is used to communicate a booking confirmation when you have chosen not to wait for confirmation whilst using the Booking API (i.e. waitForConfirmation = false). In this situation we will make a POST request in JSON format to the URL you specified in the labelDeliveryWebhook field. Your endpoint must return an HTTP 200 status code after processing our request successfully.

Example request

{
  "jobId" : 12345,
  "trackingNumber" : 9876543210,
  "carrierName" : "ABC Transport",
  "serviceName" : "EXPRESS",
  "pickupDate" : "2017-09-01",
  "expectedDeliveryDate" : "2017-09-04",
  "labelUrl" : "https://www.freightexchange.com.au/secure/getJobAttachment?jobId=1234&fileId=9876&download=true",
  "labelPdf" : "PDF_DATA"
}

Request parameters

Parameter Type Description
jobId number FreightExchange booking number
trackingNumber text Carrier’s tracking number
carrierName text Name of the carrier who will handle the shipment.
serviceName text Name of the carrier’s service.
pickupDate date Expected pick-up date.
expectedDeliveryDate data Expected delivery date.
labelUrl text URL to download shipping labels.
labelPdf base64 Base 64 representation of the shipping labels in PDF format.

Errors

The FreightExchange API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request could not be processed, most likely because it is not in the correct format or is missing a parameter
401 Unauthorized – Your security token is invalid