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.

Authentication

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

securityToken: xxxxxxxxxxxxxxxxxx

We will issue separate tokens for our development and live environments. You can obtain an API token for our live system via the ‘My Company Details’ page after logging in to FreightExchange. If you need any help obtaining API tokens then please get in touch.

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 (PRIVATE)
minTransitTime number The minimum expected transit time in working days
maxTransitTime number The maximum expected transit time in working days

Quote (Version 2)

Get A Quote

This endpoint is used to obtain a quote from FreightExchange. Our V2 quoting API can be used in two main ways:

The main difference between these two use cases is the amount of information that you should supply in your API request which naturally impacts the amount of data you have to collect from your own users. If you only want to display freight prices and have no intention of that workflow proceeding to a confirmed shipment then you only need to supply the origin city and post code, the destination city and post code, an intended pick-up date and the type, weight and dimensions of the items. You can optionally supply an insurance value if you wish.

Alternatively if your workflow is likely to result in the your user confirming an order and therefore requiring a shipment to be booked with FreightExchange you can send a much greater amount of information in your request. This can include full addresses for both origin and destination and various other pieces of information. By operating in this way you make the call to the Booking API much simpler and won’t require any extra information from your own users.

It is important to note that you can always proceed from a quote API request/response to a booking API request/response. These APIs work in tandem to collect all the information required to quote and then book a shipment - you generally can decide which of these to supply the detailed information to. We encourage you to select the option that works best for your own system design and workflow.

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/2.0/quote

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

Migrating from v1 quote API

The overall request structure for the v2 quote API is very similar to the original v1 quote API so we anticipate migrating being a relatively simple task in most cases. Whilst the V2 request has a number of extra fields these are mostly optional. We do however want to draw your attention to two crucial and breaking changes that we have made.

Example request

{
  "originSuburb":"",
  "originState":"NSW",
  "originPostCode":"2020",
  "originCountryCode":"AU",
  "originCompanyName":"TEST SHIPPER",
  "originContactName":"MRS SENDER",
  "originPhoneNumber":"0212341234",
  "originEmail":"test@test.com",
  "originUnit":"1",
  "originNumber":"123",
  "originStreet":"TEST ROAD",
  "originOpeningTime":null,
  "originClosingTime":null,
  "originCity":"MASCOT",
  "originResidential":false,
  "destinationSuburb":"",
  "destinationState":"VIC",
  "destinationPostCode":"3004",
  "destinationCountryCode":"AU",
  "destinationCompanyName":"TEST RECIPIENT",
  "destinationContactName":"MR RECIPIENT",
  "destinationPhoneNumber":"0398769876",
  "destinationEmail":"test2@test2.com",
  "destinationUnit":"2",
  "destinationNumber":"234",
  "destinationStreet":"TEST AVENUE",
  "destinationOpeningTime":null,
  "destinationClosingTime":null,
  "destinationCity":"MELBOURNE",
  "destinationResidential":false,
  "pickupDate":"2017-12-20 00:00:00",
  "depotDropOff":false,
  "depotCollection":false,
  "echoDetails":false,
  "freightType":"OTHER",
  "tailLiftPickup":false,
  "tailLiftDelivery":false,
  "securityToken":"XXXXXX",
  "resultOutput":"FULL",
  "insuranceValue":1500,
  "useSpecifiedPickupDate":false,
  "items":[
    {
      "length":0.5,
      "width":0.4,
      "height":0.3,
      "weight":22,
      "quantity":1
    },
    {
      "length":0.44,
      "width":0.33,
      "height":0.22,
      "weight":10,
      "quantity":2
    }
  ]}

Input Parameters

Parameter Type Mandatory Description
pickupDate date Y Intended pick-up date for the shipment. See notes below regarding pick-up dates.
originCompanyName text N Company name at origin.
originContactName text N Contact name at origin.
originPhoneNumber text N Phone number for origin contact.
originEmail text N Email address for origin contact.
originUnit text N Unit number of origin address.
originNumber text N Street number of origin address.
originStreet text N Street name of origin address.
originSuburb text N Sub-location of origin address.
originCity text Y Origin city.
originState text N Origin state - use the standard abbreviation (e.g. NSW, VIC, FL, NY).
originPostCode text Y Origin post code.
originCountryCode text Y Origin country - use standard ISO country codes (e.g. AU, US).
originResidential boolean Y Indicates if the origin address is residential.
originOpeningTime time N Opening time of origin address. Use HH:MM format if specifying. If this is not specified then it will default to 09:00.
originClosingTime time N Closing time of origin address. Use HH:MM format if specifying. If this is not specified then it will default to 17:00.
destinationCompanyName text N Company name at destination.
destinationContactName text N Contact name at destination.
destinationPhoneNumber text N Phone number for destination contact.
destinationEmail text N Email address for destination contact.
destinationUnit text N Unit number of destination address.
destinationNumber text N Street number of destination address.
destinationStreet text N Street name of destination address.
destinationSuburb text N Sub-location of destination address.
destinationCity text Y Destination city.
destinationState text N Destination state - use the standard abbreviation (e.g. NSW, VIC, FL, NY).
destinationPostCode text Y Destination post code.
destinationCountryCode text Y Destination country - use standard ISO country codes (e.g. AU, US).
destinationResidential boolean Y Indicates if the destination address is residential.
destinationOpeningTime time N Opening time of destination address. Use HH:MM format if specifying. If this is not specified then it will default to 09:00.
destinationClosingTime time N Closing time of destination address. Use HH:MM format if specifying. If this is not specified then it will default to 17:00.
freightType text Y The type of freight being shipped. Possible values are PALLETS or OTHER.
shipperReference text N Your reference for this quote.
shipperReference2 text N Your second reference for this quote.
tailLiftPickup boolean N Indicates if a tail lift vehicle is required for pick-up. If this is not specified then it will default to false.
tailLiftDelivery boolean N Indicates if a tail lift vehicle is required for delivery. If this is not specified then it will default to false.
depotDropOff boolean N Set to true if you are intending to drop the shipment at the carrier’s depot and therefore do not require it to be collected. If this value is not specified then false will be assumed.
depotCollection boolean N Set to true if the recipient will collect the shipment from the carrier’s depot. If this value is not specified then false will be assumed.
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 on 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.

Example response

{
    "success": true,
    "quoteId": 256989,
    "insuredValue": 1500,
    "priceResult": [
        {
            "priceId": 4043167,
            "freightPrice": 22.21,
            "insurancePrice": 13.5,
            "consignmentFee": 0,
            "netPrice": 35.71,
            "gst": 3.57,
            "grossPrice": 39.28,
            "priceType": "FE",
            "carrierName": "ABC TRANSPORT",
            "serviceName": "ECONOMY",
            "serviceCategory" : "ECONOMY",
            "minTransitTime": 1,
            "maxTransitTime": 2
        },
        {
            "priceId": 4043169,
            "freightPrice": 29.88,
            "insurancePrice": 13.5,
            "consignmentFee": 0,
            "netPrice": 43.38,
            "gst": 4.34,
            "grossPrice": 47.72,
            "priceType": "FE",
            "carrierName": "XYZ COURIERS",
            "serviceName": "EXPRESS",
            "serviceCategory" : "EXPRESS",
            "minTransitTime": 1
        }
    ]
}

Response parameters

Parameter Type Description
success boolean Indicates if the quote was successful or not
quoteId number FreightExchange reference for this quote
insuredValue number The value being covered by FreightExchange’s insurance for this quote
shipperReference text If you specified a value for shipperReference in the quote request it will be returned in this parameter. This may be useful if you need to link the quote to a record in your own system.
shipperReference2 text If you specified a value for shipperReference2 in the quote request it will be returned in this parameter. This may be useful if you need to link the quote to a record in your own system.
priceResult array An array of one of more prices for the quoted shipment. If you specified resultOutput = SINGLE in your request only one priceResult will be returned. See below for details of the parameters returned in the priceResult node.

The parameters returned in the priceResult node are as follows:

Parameter Type Description
priceId number A unique identifier for this price. If you are planning to use our Booking endpoint to book a specific price then you will need to record this value for use in that request.
freightPrice number The cost of freight for this option. This excludes the cost of insurance cover but does include all known carrier surcharges.
insurancePrice number The cost of insurance for this option.
consignmentFee number The FreightExchange consignment fee that would apply if this option is booked.
netPrice number The total net price applicable for this option - this included freight, insurance and the consignment fee.
gst number The total amount of sales tax that applies to this option. Please note that this value can be zero as not all freight services are subject to sales tax.
grossPrice number The gross price for this option - this will be netPrice plus gst.
priceType text If FE then this price is from a FreightExchange carrier. If NETWORK then the price is from one of your own carrier’s accounts.
serviceName text The service name for this option.
serviceCategory text The category of service for this option. This field can be used to offer your customers a range of service levels, such as ECONOMY or EXPRESS. Please contact us for more information about this option.
carrierName text The name of the carrier for this option. This information will only be returned if your account has been setup to provide it - please contact us for more information.
minTransitTime number The minimum expected transit time in working days.
maxTransitTime number The maximum expected transit time in working days.

Book

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:

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/2.0/book

Live https://api.freightexchange.com.au/2.0/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 - book cheapest price, do not wait for booking to be confirmed, no labels to be sent.

{
  "quoteId": 11111,
  "waitForConfirmation":false,
  "freightDescription":"TEST DESCRIPTION",
  "labelDeliveryMethod":"NONE",
  "securityToken":"XXXXXXXXXXXXX"
}

Example request - book a specific price, do not wait for booking to be confirmed, no labels to be sent.

{
  "quoteId": 11111,
  "priceId": 222222,
  "waitForConfirmation":false,
  "freightDescription":"TEST DESCRIPTION",
  "labelDeliveryMethod":"NONE",
  "securityToken":"XXXXXXXXXXXXX"
}

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

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

Input parameters

Parameter Type Mandatory Description
securityToken text Y
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 Y 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.
shipperReference2 text N* A second 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 Y* 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 * in the mandatory column 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.

Example response

{
  "jobId":5893,
  "carrierName":"ABC TRANSPORT",
  "serviceName":"ECONOMY",
  "expectedDeliveryDate": "2018-02-02 09:00:00",
  "freightPrice":13.08,
  "netPrice":13.08,
  "grossPrice":14.39,
  "gst":1.31,
  "insurancePrice":0.0,
  "maxTransitTime":1,
  "minTransitTime":1,
  "priceId":276114,
  "priceType":"FE",
  "consignmentFee":0.0
}

Response parameters

Parameter Type Description
jobId number FreightExchange booking number
trackingNumber text Carrier’s tracking number if the booking has been confirmed
carrierName text Name of the carrier who will handle the shipment.
serviceName text Name of the carrier’s service.
expectedDeliveryDate date Expected delivery date.
freightPrice number The price (excluding GST) that will be charged based on the details provided
grossPrice number The price (including GST) that will be charged based on the details provided
gst number The amount of GST that will be charged
insurancePrice number The cost of transit insurance for the shipment
maxTransitTime number The maximum expected transit time in working days
minTransitTime number The minimum expected transit time in working days
shipperReference text Your reference for this shipment if one was provided.
shipperReference2 text Your second reference for this shipment if one was provided.
priceId number The price ID that was booked
priceType text If FE then this price is from a FreightExchange carrier. If NETWORK then the price is from one of your own carrier’s accounts.
consignmentFee number The consignment fee charged by FreightExchange for this booking
shippingLabelUrl text URL to download shipping labels if they have been generated
shippingDocs base64 Base 64 representation of the shipping labels in PDF format if they have been generated

Booking without a quote

HTTP request

Dev https://apidemo.freightexchange.com.au/2.0/book/direct

Live https://api.freightexchange.com.au/2.0/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.

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.

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

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.

Tracking

The API endpoints below will allow you obtain tracking information about jobs you have booked with FreightExchange. At present you will need to use the Job ID we give you when the job is booked.

Status

This tracking API will return the most recent event that has been recorded against the specified job.

HTTP request

This endpoint will only accept GET requests.

Dev https://apidemo.freightexchange.com.au/2.0/track/JOB_ID/status?securityToken=SECURITY_TOKEN

Live https://api.freightexchange.com.au/2.0/track/JOB_ID/status?securityToken=SECURITY_TOKEN

Request parameters

Parameter Type Mandatory Description
JOB_ID Number Y The FreightExchange job ID you want the status for
SECURITY_TOKEN Text Y Your FreightExchange API security token

Response

Example response

{
    "id": 1450,
    "eventCode": "PBK",
    "eventDescription": "Pick-up booked with carrier",
    "eventDateLocal": "2017-10-29 22:00:00",
    "eventDateUTC": "2017-10-30 09:00:00",
    "eventCity": null,
    "eventState": null,
    "eventPostCode": null,
    "eventCountryCode": null,
    "eventNotes": null,
    "eventSignature": null
}

Response parameters

This endpoint will return a single event with the following fields:

Parameter Type Description
id Number Internal reference for the event
eventCode Text FreightExchange code for the event type
eventDescription Text User friendly description of the event type
eventDateLocal Date Date and time the event occurred, local to where it happened
eventDateUtc Date Date and time the event occurred, coverted to UTC
eventCity Text Name of the city where the event occurred
eventState Text Name of the state where the event occurred
eventPostCode Text Post code where the event occurred
eventCountryCode Text Two character ISO code for the country where the event occurred
eventNotes Text Any notes that were recorded for the event
eventSignatures Text For a DEL (Delivery) event this will be the name of the person who signed for the shipment (POD)

Please note that the eventCity, eventState, eventPostCode and eventCountryCode fields will not always be populated as this data is not made available to us by all carriers.

Events

This tracking API will return all events that have been recorded against the specified job, with the oldest event first.

HTTP request

This endpoint will only accept GET requests.

Dev https://apidemo.freightexchange.com.au/2.0/track/JOB_ID?securityToken=SECURITY_TOKEN

Live https://api.freightexchange.com.au/2.0/track/JOB_ID?securityToken=SECURITY_TOKEN

Request parameters

Parameter Type Mandatory Description
JOB_ID Number Y The FreightExchange job ID you want the events for
SECURITY_TOKEN Text Y Your FreightExchange API security token

Response

Example response

[
    {
        "id": 968,
        "eventCode": "JBK",
        "eventDescription": "Job booked",
        "eventDateLocal": "2017-10-27 09:18:31",
        "eventDateUTC": "2017-10-26 22:18:31",
        "eventCity": "",
        "eventState": "",
        "eventPostCode": "",
        "eventCountryCode": "",
        "eventNotes": "",
        "eventSignature": null
    },
    {
        "id": 1450,
        "eventCode": "PBK",
        "eventDescription": "Pick-up booked with carrier",
        "eventDateLocal": "2017-10-29 22:00:00",
        "eventDateUTC": "2017-10-30 09:00:00",
        "eventCity": "",
        "eventState": "",
        "eventPostCode": "",
        "eventCountryCode": "",
        "eventNotes": "",
        "eventSignature": ""
    }
]

Response parameters

This endpoint will return an array of events with the following fields:

Parameter Type Description
id Number Internal reference for the event
eventCode Text FreightExchange code for the event type
eventDescription Text User friendly description of the event type
eventDateLocal Date Date and time the event occurred, local to where it happened
eventDateUtc Date Date and time the event occurred, coverted to UTC
eventCity Text Name of the city where the event occurred
eventState Text Name of the state where the event occurred
eventPostCode Text Post code where the event occurred
eventCountryCode Text Two character ISO code for the country where the event occurred
eventNotes Text Any notes that were recorded for the event
eventSignatures Text For a DEL (Delivery) event this will be the name of the person who signed for the shipment (POD)

Please note that the eventCity, eventState, eventPostCode and eventCountryCode fields will not always be populated as this data is not made available to us by all carriers.

Supporting APIs

The API endpoints listed below provide access to information that helps you integrate your system with FreightExchange. Typically these provide access to our standing data which is useful for looking up values or providing choices to your users.

Depot lookup

This endpoint allows you to obtain a list of our carrier’s depots that are close to a location you specify. A typical use of this endpoint is where you want to offer your users the option to have their items delivered to the carrier’s depot instead of their actual address.

The searchLocation you provide can be either a city/suburb or post code that is valid in the specified countryCode. Remember to include your securityToken in every request.

The API will look for all depots within a 50 kilometer radius of the location you enter. When you search using a post code, the search location will typically be the centre point of that post code area unless otherwise defined by our data provider. If you search using a suburb or city name you could potentially receive depots from various locations in the country if the suburb name is not unique. We will also return a distance value which is the approximate distance, in kilometers, between your search location and each depot. This distance is “as the crow flies” and does not reflect driving distance.

HTTP Request

This endpoint will only accept GET requests.

Dev https://apidemo.freightexchange.com.au/2.0/support/depotlookup?countryCode=COUNTRY_CODE&searchLocation=SEARCH_LOCATION&securityToken=SECURITY_TOKEN

Live https://api.freightexchange.com.au/2.0/support/depotlookup?countryCode=COUNTRY_CODE&searchLocation=SEARCH_LOCATION&securityToken=SECURITY_TOKEN

Request parameters

Parameter Type Mandatory Description
COUNTRY_CODE Text Y The two character ISO country code (e.g. AU, GB) for the country you are looking up depots
SEARCH_LOCATION Text Y The suburb/city or post code you wish to find depots nearest to
SECURITY_TOKEN Text Y Your FreightExchange API security token

Response

Example response

[
    {
        "countryCode": "AU",
        "suburb": "BOTANY",
        "postCode": "2019",
        "state": "NSW",
        "distance": 9
    },
    {
        "countryCode": "AU",
        "suburb": "ERSKINE PARK",
        "postCode": "2759",
        "state": "NSW",
        "distance": 44
    }
]

Response parameters

Parameter Type Description
countryCode Text The two character ISO country code for the depot
suburb Text The suburb or city where the depot is located
postCode Text The post code of the depot
state Text The state where the post code is located, if the country has states
distance Number The approximate distance in kilometers between your search location and each depot

Response codes

This API can return one of four HTTP status codes:

Code Meaning
200 Depots have been found (a list will be returned)
400 An error has occurred
401 The securityToken you supplied is not valid
404 No depots could be found within a 50km radius of the specified location

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