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.
Audience
This documentation is intended to be read and used by web developers who are familiar with concepts such as AJAX, JSON and REST APIs. It is not intended to be used by anyone who is not familiar with developing web pages.
Correct format for requests
Many of our APIs accept POST requests. When accessing these endpoints you must send the data in the BODY of the request and ensure it is correctly formatted as JSON. You should also make sure the Content-Type of the request is set to application/json. If you do not submit requests in the correct way you will most likely receive a generic 405 error from us.
The request type for each endpoint is clearly detailed below, along with example requests.
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.
With our Australian Domestic APIs, the securityToken is ALWAYS passed in the body of the request. For our Ocean Freight APIs the securityToken can be passed in either the body of the request or the headers.
Australia Domestic 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, you must set the Content-Type of your request to application/json.
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
- The
pickupDateyou specify must be the current day or in the future. It must also not be a public holiday in the origin state. - The suburbs and post codes you provide will be validated against the Australia Post database.
- Our version 1 Quote API only supports Australian domestic shipments.
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 |
Australia Domestic 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:
- As a simple freight quoting tool, for example to provide an estimated shipping cost to your customers
- As the first step in a freight booking process
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, you must set the Content-Type of your request to application/json.
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.
- The value you sent in
originSuburbin v1 must now be sent inoriginCity.originSuburbis now used for a sub-location in some countries. - The value you sent in
destinationSuburbin v1 must now be sent indestinationCity.destinationSuburbis now used for a sub-location in some countries.
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. |
| destinationPoBox | boolean | N | Indicates if the destination address is a PO Box (see notes for more details) |
| 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 |
If you wish to get a quote for shipping Dangerous Goods the following parameters can also be included. If these fields are not included then the system will assume that the items you are planning to ship are not Dangerous. Please note that we do not validate UN Numbers, DG Classes or Packing Groups.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| dg | boolean | Y* | Indicates if the items are classified as Dangerous. Whilst it is not required to supply the subsequent fields we strongly encourage you to provide as much Dangerous Goods information as possible. |
| unNumber | text | N | The correct UN number for the items being shipped. |
| dgClass | text | N | The Dangerous Goods class for the items. This should be passed using the standard convention, for example 1.1, 3, 4.2. |
| dgSubRisk | text | N | The sub risk for the items. |
| dgPackGroup | text | N | The packing group for the items. This should be passed as I, II or III. |
| dgHazChem | text | N | The Haz Chem code for the items. |
Dimensions or volumes
Our quoting API supports sending either the length, width and height (dimensions) or the volume of the items you wish to ship. You must specify either the dimension or the volume in order to get a quote. If you specify both, we will use the dimensions to calculate the quote.
It is important to understand that if you only specify the volume we cannot provide a 100% accurate quote as some carriers have surcharges for items over a certain length, width or height. However for smaller items (less than approximately 1.1m in all dimensions) the quote will typically be accurate. By sending only the volume when getting a quote you understand that the price charged for the shipment may vary from our quoted price.
Please also be aware that our booking API does not support using volume in place of dimensions.
Validation Rules
- The
pickupDateyou specify must be the current day or in the future. It must also not be a public holiday in the origin state. - The suburbs and post codes you provide will be validated against the Australia Post database for origins and destinations in Australia.
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.
Dangerous Goods
You are able to obtain quotes for shipping goods that are classed as Dangerous (DG) using the fields shown above. If you wish to obtain quotes and ship Dangerous Goods via our platform this needs to specifically enabled so please contact us if that is the case. It is essential that all items are declared correctly and shipping undeclared Dangerous Goods is a serious offence.
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",
"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",
"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. |
| 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. |
Australia Domestic Booking
Introduction
Our booking endpoint allows you to make an Australia domestic 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:
- Get a quote using the Quote API, then make a booking for either the cheapest price or one of your choosing.
- Make a booking without getting a quote, automatically choosing the cheapest price or a carrier that you specify.
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, you must set the Content-Type of your request to application/json.
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.
This endpoint behaves differently if you have consolidation enabled on your account. If this option - which combines shipments travelling to and from the same place - is enabled then bookings are queued for creation and therefore the response from this endpoint will only show your references, and will not include a jobId or trackingNumber. You are strongly encouraged to provide a webhook when using consolidation so that these details and labels can be pushed to your system. If you do not provide a webhook to receive these details then users will have to manually locate consolidated jobs via the FreightExchange website. In addition, the waitForConfirmation flag has no effect when consolidation is enabled on your account.
Consolidation is a complicated subject so please contact us if you need further information and guidance with how this option affects the FreightExchange platform and how you interact with it.
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. |
| authorityToLeave | boolean | N | If set to true we will, where possible, indicate to the carrier that the item can be delivered without obtaining a signature. Note that not all carriers support 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.
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.
This endpoint behaves differently if you have consolidation enabled on your account. If this option - which combines shipments travelling to and from the same place - is enabled then bookings are queued for creation and therefore the response from this endpoint will only show your references, and will not include a jobId or trackingNumber. You are strongly encouraged to provide a webhook when using consolidation so that these details and labels can be pushed to your system. If you do not provide a webhook to receive these details then users will have to manually locate consolidated jobs via the FreightExchange website. In addition, the waitForConfirmation flag has no effect when consolidation is enabled on your account.
Consolidation is a complicated subject so please contact us if you need further information and guidance with how this option affects the FreightExchange platform and how you interact with it.
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 |
| destinationPoBox | boolean | N | Indicates if the destination address is a PO Box (see notes for more details) |
| deliveryInstructions | text | N | Any instructions to be passed to the delivering driver. |
| authorityToLeave | boolean | N | If set to true we will, where possible, indicate to the carrier that the item can be delivered without obtaining a signature. Note that not all carriers support this option. |
| 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. |
| shipperReference2 | text | N | Your second reference for this shipment. |
| shipperReference3 | text | N | Your third reference for this shipment. |
| 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.
Shipper reference fields
Our booking API provides three reference fields, shipperReference and shipperReference2 and shipperReference3. You are free to use these fields for any references that you want to pass to FreightExchange and we will simply store the values you send. The value in shipperReference will be passed to the carrier when we book your shipment and will typically be printed on shipping labels. Where you are booking freight on your own carrier account this reference will usually be included on the carrier’s invoice. Finally, we will also include all these references in the messages we send you, for example after booking and when pushing events to your webhook. You should therefore consider using these fields to make it easier to link our messages to your own systems.
Please note that when consolidation is enabled on your account the response from the booking endpoints will ONLY include the references you send in the request.
Post Office (PO) Box deliveries
We support deliveries to PO Boxes in Australia via the booking APIs for customers using their own carrier accounts, however there are some considerations that must be taken into account if you wish to use this option. Firstly there are two ways to indicate that your shipment is destined for a PO Box. The first is to set the destinationPoBox field to true in your request. If this is done then we will treat the destination address as being a PO Box regardless of the actual address content. Alternatively we will process the conent of the address and attempt to identify if it is a PO Box using common terms such as PO Box, P.O. Box, Locked Bag and so on.
The second, and very important consideration, is having a carrier available in your profile who can make deliveries to PO Boxes. At present, in Australia, this is limited to Australia Post and Startrack. If you do not have an account with one of these carriers you will not be able to send shipments to PO Boxes via FreightExchange. However if you do have an account setup we will automatically transfer shipments destined for PO Boxes to your Australia Post or Startrack account regardless of the carrier selected in your request.
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 |
If you wish to ship Dangerous Goods the following parameters can also be included. If these fields are not included then the system will assume that the items you are planning to ship are not Dangerous. Please note that we do not validate UN Numbers, DG Classes or Packing Groups.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| dg | boolean | Y* | Indicates if the items are classified as Dangerous. |
| unNumber | text | Y | The correct UN number for the items being shipped. |
| dgClass | text | Y | The Dangerous Goods class for the items. This should be passed using the standard convention, for example 1.1, 3, 4.2. |
| dgSubRisk | text | N | The sub risk for the items. |
| dgPackGroup | text | N | The packing group for the items. This should be passed as I, II or III. |
| dgHazChem | text | N | The Haz Chem code for the items. |
Dangerous Goods
You are able to ship goods that are classed as Dangerous (DG) using the fields shown above. If you wish to obtain quotes and ship Dangerous Goods via our platform this needs to specifically enabled so please contact us if that is the case. It is essential that all items are declared correctly and shipping undeclared Dangerous Goods is a serious offence.
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. |
Ocean Freight (BETA)
Introduction
FreightExchange now has APIs available for Ocean Freight shipments. At this time these APIs allow you to obtain quotes and book full container loads (FCL) only. In order to use these APIs you have must have access to our ocean freight module, if you do not please contact us for assistance.
Authentication
You can continue to use your existing FreightExchange API keys for all Ocean Freight APIs, however you can now include the securityToken value in either your request header or request body. In the example requests below we have assumed you will be placing this information in the header and it is therefore not included in the example requests.
Request format
Please ensure you always set your Content-Type to application/json as otherwise the request will fail.
Standard values
The ocean freight APIs use industry standard values in many fields. These are documented below for your reference.
Container types
We use ISO container type codes. Common values are listed below.
| Code | Container type |
|---|---|
2200 |
20’ general |
45G0 |
40’ general |
4500 |
40’ high-cude |
Incoterms
| Incoterm | Description |
|---|---|
EXW |
Ex Works |
FCA |
Free Carrier |
CPT |
Carriage Paid To |
CIP |
Carriage And Insurance Paid To |
DAT |
Delivered At Terminal |
DAP |
Delivered At Place |
DDP |
Delivered Duty Paid |
FAS |
Free Alongside Ship |
FOB |
Free On Board |
CFR |
Cost and Freight |
CIF |
Cost, Insurance and Freight |
Party role codes
| Code | Description |
|---|---|
Carrier |
The carrier transporting the shipment |
Shipper |
The entity shipping the shipment |
Consignee |
The recipient |
Forwarder |
The freight forwarder |
NotifyParty |
Any party who is to be notified about the shipment |
AlsoNotifyParty |
Additional parties to be notified |
BookingParty |
The entity making the booking |
ShipFrom |
The origin party |
ShipTo |
The destination party |
ContainerLocation |
The location where the container is obtained |
CustomsBroker |
The details of the customs broker |
Ventilation setting codes
| Code | Description |
|---|---|
OPN10 |
Vent 10% Open |
OPN25 |
Vent 25% Open |
OPN50 |
Vent 50% Open |
OPN75 |
Vent 75% Open |
OPN100 |
Vent 100% Open |
OTHER |
Others |
CLOSED |
Closed |
Quote
This endpoint is used to obtain a quote for an ocean freight shipment. You must provide basic details of the shipment including origin, destination and quantity and type of containers being shipped. Ocean freight quotes typically have a limited validity due to carrier rates changing on a regular basis and you are therefore encouraged to call this API regularly if you are storing quotes in your own system.
HTTP request
This endpoint will only accept POST requests, please ensure you set the Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/2.0/quote/container
Live https://api.freightexchange.com.au/2.0/quote/container
Example request
{
"destinationCity": "",
"destinationCountryCode": "",
"destinationPostCode": "",
"destinationUNLocode": "AUSYD",
"filterResults": "FULL",
"originCity": "",
"originCountryCode": "",
"originPostCode": "",
"originUNLocode": "CNYTN",
"pickUpDate": "2019-07-11",
"quoteItems": [
{
"quantity": "1",
"containerTypeISO": "42G0",
"containerWeight": "20000"
}
]
}
Request parameters
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| destinationCity | text | N | The destination city for the shipment. |
| destinationCountryCode | text | N | The destination country code (ISO two character code) for the shipment. |
| destinationPostCode | text | N | The destination post code for the shipment. |
| destinationUNLocode | text | N | The destination UNLOCODE for the shipment. |
| filterResults | text | Y | If FULL is specified then all matching results will be returned. If any other value is specified only the cheapest price will be returned. |
| originCity | text | N | The origin city for the shipment. |
| originCountryCode | text | N | The origin country code for the shipment. |
| originPostCode | text | N | The origin post code for the shipment. |
| originUNLocode | text | N | The origin UNLOCODE for the shipment. |
| pickUpDate | date | Y | Date the items are intended to be ready in YYYY-MM-DD format. |
| quoteItems | Y | An array of containers you want to a quote for. Please see Quote items below for details. At least one item must be specified. |
Note: Whilst all destination and origin fields are shown as non-mandatory you must supply sufficient information to allow an origin and destination to be determined. Providing origin and destination UNLOCODEs is the most precise way to obtain a quote assuming you have that information. Alternatively a city can be specified to be matched against a list of ports.
Quote items
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| quantity | number | Y | The number of containers of the specified type and weight being shipped. |
| containerTypeISO | text | Y | The ISO type of container - see list provided above. |
| containerWeight | number | Y | The total weight of the container in KG. |
Example response
{
"success": true,
"quoteId": 92374,
"originUnlocode": "CNYTN",
"destinationUnlocode": "AUSYD",
"originPortName": "YANTIAN",
"destinationPortName": "SYDNEY",
"pickUpDate": "2019-07-22 00:00:00",
"incoterm": null,
"movementType": null,
"prices": [
{
"priceId": 1058872,
"quantity": 1,
"sameCurrency": true,
"carrierName": "ABC",
"totalPrice": 1234.45,
"currency": "AUD",
"quoteTransportId": 1058872,
"minTransitTime": 7,
"maxTransitTime": 7,
"departureDateLocal": "2019-07-26",
"arrivalDateLocal": "2019-08-02",
"selectedScheduleId": 44,
"vesselName": "VS001",
"voyageNumber": "Voyage001",
"originUNLOCODE": "CNYTN",
"destinationUNLOCODE": "AUSYD",
"feederUNLOCODE": null,
"validUntil": null,
"expired": null,
"items": [
{
"rateId": 10010,
"rate": 888.99,
"currency": "USD",
"containerIsoTypeCode": "42G0",
"containerIsoTypeDescriotion": "40' 8'6 GENERAL",
"quantity": 1,
"carrierId": 1407,
"carrierName": "ABC"
}
]
}
]
}
Response parameters
| Parameter | Type | Description |
|---|---|---|
| success | boolean | Indicates if the quote was successfully generated. |
| quoteId | number | Unique FreightExchange reference for this quote. If you plan to make a booking using this quote then you should store this value. |
| originUnlocode | text | The origin UNLOCODE for the quote. |
| destinationUnlocode | text | The destination UNLOCODE for the quote. |
| originPortName | text | The origin port name for the quote. |
| destinationPortName | text | The destination port name for the quote. |
| pickUpDate | date | The pick-up date for the shipment. |
| incoterm | text | If specified the incoterm that applies to this quote. |
| movementType | text | For future use. |
| prices | An array of one or more prices - see definition below. |
Prices response
| Parameter | Type | Description |
|---|---|---|
| priceId | number | Unique FreightExchange reference for this price. If you plan to make a booking using this price then you should store this value. |
| quantity | number | The number of containers being quoted. |
| sameCurrency | boolean | Indicates if all the containers are being quoted in the same currency. |
| carrierName | text | The name of the carrier providing the quote. |
| totalPrice | number | The total prices, including all mandatory surcharges, origin and destination charges. |
| currency | text | Three character code for the currency that totalPrice is expressed in. |
| quoteTransportId | number | Unique FreightExchange reference for this price. |
| minTransitTime | number | Start of transit time range. |
| maxTransitTime | number | End of transit time range. |
| departureDateLocal | date | Date (local to location) that the vessel departs origin port. |
| arrivalDateLocal | date | Date (local to location) that the vessel arrives at the destination port. |
| selectedScheduleId | number | Reference to the voyage schedule. |
| vesselName | text | Name of the vessel scheduled to perform the voyage. |
| voyageNumber | text | Voyage number as published by the carrier. |
| originUNLOCODE | text | UNLOCODE for origin port. |
| destinationUNLOCODE | text | UNLOCODE for destination port. |
| feederUNLOCODE | text | UNLOCODE for port where feeder vessel departs if applicable. |
| validUntil | date | Date the rate is valid until. Typically bookings must be made by this date for the rate to be honoured by the carrier. |
| expired | boolean | Indicates if the rate has expired. |
| items | One or more prices for individual containers. |
Price item response
| Parameter | Type | Description |
|---|---|---|
| rateId | number | Identifier for the published rate. |
| rate | number | The price for the specified container. |
| currency | text | The currency for this rate. This currency will be the one published by the carrier and may be different to the currency used to provide the totalPrice. |
| containerIsoTypeCode | text | The ISO code for the container type being quoted. |
| containerIsoTypeDescriotion | text | Description of the container type. |
| quantity | number | The number of containers being quoted. |
| carrierId | number | FreightExchange identifier for the carrier. |
| carrierName | text | The name of the carrier. |
Introduction to ocean freight bookings
Our ocean freight booking APIs take into account that ocean freight takes longer to arrange on the shipper’s side due to the need to obtain various pieces of information from parties around the world. There are therefore a number of endpoints that you can use during the booking process. It is also possible to switch between using APIs and the FreightExchange website to update bookings at any time. This provides you with the flexibility to capture information in the easiest or most appropriate place.
When sending updates to the booking APIs it is important to understand that we will OVERWRITE existing details with the information you send. This means that if you include a blank value for a field that was previously populated that value would be overwritten.
Make booking
The make booking endpoint, which is used to create a new booking is effectively a combination of various sub components each of which can be accessed via their own endpoint. The description for each of these sub components can be found in the appropriate section.
HTTP Request
Example request
{
"quoteId": 91103,
"priceId": 1058329,
"cargoTerms": {
"containerLoad": "FCL",
"incoterm": "FOB",
"paymentMethod": "PREPAID"
},
"parties": [
{
"partyRoleCode": "Carrier",
"locationType": "NONE",
"partyName": "Hello World",
"address": {
"address2": "Address 2",
"city": "Sydney",
"number": "1",
"postCode": "2000",
"state": "NSW",
"street": "2114",
"unit": "1"
},
"contact": {
"contactName": "Mr John Smith",
"email": "john.smith@test.com",
"fax": "090909090",
"phone": "04343879877"
},
"references": {
"COMPANY": "943"
}
},
{
"partyRoleCode": "Shipper",
"locationType": "NONE",
"references": {
"USER_ADDRESS": "10602"
}
}
],
"equipments": [
{
"locations": [
{
"locationType": "POL",
"unlocode": "CNYTN",
},
{
"locationType": "FND",
"locationName": "Hello World",
"address": {
"address2": "",
"city": "Sydney",
"number": "1",
"postCode": "2000",
"state": "NSW",
"street": "Test Street",
"unit": "1",
"countryCode": "AU"
},
"contact": {
"contactName": "Jane Jones",
"email": "jane.jones@test.com",
"fax": "090909090",
"phone": "04343879877"
},
"references": {
"COMPANY": "943"
}
},
{
"locationType": "POD",
"locationName": "Hello World",
"unlocode": "AUSYD"
}
],
"equipmentType": "22G",
"equipmentDates": {
"REQUESTED_PICKUP": "2019-10-01T00:00:00Z",
"EMPTY_EQUIPMENT_PLACEMENT":"2019-10-01T00:00:00Z",
"REQUESTED_DELIVERY": "2019-10-01T00:00:00Z",
"EMPTY_EQUIPMENT_RETURN": "2019-10-01T00:00:00Z"
},
"quantity": "1",
"socIndicator": false,
"references": {
"TEST_TEST": "Hello World"
},
"grossWeight" : {
"unit" : "KG",
"value": "123.123"
},
"settings" : {
"atmosphereType" : "CA",
"co2Level" : {"value": "123"},
"o2Level" : {"value" : "11.22"},
"dehumidity" : {"value":"111.22"},
"preCooling" : false,
"genSetType" : "NR",
"sensitiveCargoDesc" : "Hello World",
"temperature" : {"value": "123.22" , "unit" : "C"},
"ventilation" : {"value": "123.22" , "unit" : "cm/h"},
"ventSettingCode" : "OPN10"
}
}
],
"route": {
"locations": [
{
"locationType": "POL",
"unlocode": "CNYTN",
},
{
"locationType": "FND",
"locationName": "Hello World",
"address": {
"address2": "",
"city": "Sydney",
"number": "1",
"postCode": "2000",
"state": "NSW",
"street": "Test Street",
"unit": "1",
"countryCode": "AU"
},
"contact": {
"contactName": "Jane Jones",
"email": "jane.jones@test.com",
"fax": "090909090",
"phone": "04343879877"
},
"references": {
"COMPANY": "943"
}
},
{
"locationType": "POD",
"locationName": "Hello World",
"unlocode": "AUSYD"
}
],
"routeDates": {
"FullReturnCutoff": "2019-10-01T00:00:00Z",
"VGMCutOffDate": "2019-10-01T00:00:00Z",
"DocumentCutOffDate": "2019-10-01T00:00:00Z",
"ReqDeliveryDate": "2019-10-01T00:00:00Z",
"ArrivalAtFinalHub": "2019-10-01T00:00:00Z"
},
"intermodals": [
{
"references": {
"Hello": "World"
},
"sequence": 1,
"transportMode": "OCEAN",
"carriageType": "MAIN",
"vesselVoyage": {
"serviceCode": "Service code",
"serviceName": "service Name",
"voyageNumber": "voyage Number",
"voyageNumberDirection": "voyage Number Direction",
"vesselCode": "vessel Code",
"vesselLloydCode": "vesse lLloyd Code",
"vesselCallSign": "vessel Call Sign",
"vesselName": "vessel Name",
"vesselCountryCode": "vessel Country Code"
},
"locations": [
{
"locationType": "POL",
"locationName": "Hello World",
"unlocode": "AUSYD",
"address": {
"address2": "Address 2",
"city": "Sydney",
"number": "1",
"postCode": "2114",
"state": "NSW",
"street": "2114",
"unit": "1",
"countryCode": "UK"
},
"contact": {
"contactName": "Mr Uditha Karunaratne",
"email": "uditha@gmail.com",
"fax": "090909090",
"phone": "04343879877"
},
"references": {
"COMPANY": "943"
}
},
{
"locationType": "POD",
"locationName": "Hello World",
"unlocode": "AUSYD",
"address": {
"address2": "Address 2",
"city": "Sydney",
"number": "1",
"postCode": "2114",
"state": "NSW",
"street": "2114",
"unit": "1",
"countryCode": "UK"
},
"contact": {
"contactName": "Mr Uditha Karunaratne",
"email": "uditha@gmail.com",
"fax": "090909090",
"phone": "04343879877"
},
"references": {
"COMPANY": "943"
}
}
]
},
{
"sequence": 2,
"transportMode": "TRUCK",
"carriageType": "PRE",
"locations": [
{
"locationType": "POD",
"locationName": "Hello World",
"unlocode": "AUSYD",
"address": {
"address2": "Address 2",
"city": "Sydney",
"number": "1",
"postCode": "2114",
"state": "NSW",
"street": "2114",
"unit": "1",
"countryCode": "UK"
},
"contact": {
"contactName": "Mr Uditha Karunaratne",
"email": "uditha@gmail.com",
"fax": "090909090",
"phone": "04343879877"
},
"references": {
"COMPANY": "943"
}
},
{
"locationType": "FND",
"locationName": "Hello World",
"unlocode": "AUSYD",
"address": {
"address2": "Address 2",
"city": "Sydney",
"number": "1",
"postCode": "2114",
"state": "NSW",
"street": "2114",
"unit": "1",
"countryCode": "UK"
},
"contact": {
"contactName": "Mr Uditha Karunaratne",
"email": "uditha@gmail.com",
"fax": "090909090",
"phone": "04343879877"
},
"references": {
"COMPANY": "943"
}
}
]
}
]
},
"references": {
"SHIPPER_REFERENCE": "SHIPPER REF 001",
"TEST_TEST": "Hello World"
}
}
This endpoint only accepts POST requests, please ensure you set Content-Type to application/json.
Live
Dev
Input Parameters
| Parameter | Mandatory | Type | Description |
|---|---|---|---|
| quoteId | Y | Integer | The FreightExchange quote reference you are booking |
| priceId | Y | Integer | The FreightExchange price reference are booking |
| securityToken | Y | Text | Your FreightExchange API security token |
| cargoTerms | Y | cargoTerms | A set of cargo terms, defined below |
| parties | Y | Array of Parties | One of more parties involed in this shipment |
| equipments | Y | Array of Equipments | One of more equipments (containers) being shipped |
| route | Y | Route details | |
| references | N | Array of References | One of more references for the shipment |
Response Parameters
For details of the response please see the Get booking section below.
Get booking
HTTP Request
This endpoint accepts GET requests only.
Dev “
Live ”
Input Parameters
| Parameter | Mandatory | Type | Description |
|---|---|---|---|
| JOB_ID | Y | number | The FreightExchange reference for the booking you wish to retrieve. |
Response Parameters
Note that this result structure is used across all booking endpoints. For details of each subsection please refer to the request for updating that section.
| Parameter | Type | Description |
|---|---|---|
| status | text | Status of the request |
| result | The detailed result |
Result response
| Parameter | Type | Description |
|---|---|---|
| bookingStatus | text | Status of the booking. DRAFT indicates that it has not been submitted and can still be edited. |
| fromUi | text | For internal use only. |
| jobId | number | Unique FreightExchange reference for the booking. |
| quoteId | number | Quote reference for this booking. |
| priceId | number | Price that was booked. |
| cargoTerms | See cargo terms response. | |
| equipments | See equipments response. | |
| parties | See parties response. | |
| cargoDetails | See cargo details response. | |
| attachments | See attachments response. | |
| route | See route response |
Example response
{
"status": "Successful",
"result": {
"bookingStatus": "DRAFT",
"fromUi": false,
"jobId": 21575,
"cargoTerms": {},
"equipments": [
{
"equipmentDates": {
"EMPTY_EQUIPMENT_PLACEMENT": null,
"REQUESTED_PICKUP": "2019-07-22T00:00:00Z",
"EMPTY_EQUIPMENT_RETURN": null,
"REQUESTED_DELIVERY": null
},
"equipmentType": "2200",
"grossWeight": {
"value": 12000.0,
"unit": "KG"
},
"id": 568,
"locations": [],
"quantity": 2,
"settings": {}
}
],
"parties": [
{
"id": 1666,
"partyRoleCode": "Carrier",
"locationType": "NONE",
"references": {
"COMPANY": "1084"
},
"address": {},
"contact": {
"email": "test+contact@au.dsv.com",
"phone": "02 8304 4400"
},
"partyName": "ABC"
},
{
"id": 1667,
"partyRoleCode": "Shipper",
"locationType": "NONE",
"references": {
"COMPANY": "8"
},
"address": {
"city": "Pyrmont",
"countryCode": "AU",
"number": "123",
"postCode": "2009",
"state": "NSW",
"street": "Any Street",
"unit": ""
},
"contact": {
"email": "hello@freightexchange.com.au",
"phone": "0481357676"
},
"partyName": "Test Company"
}
],
"cargoDetails": [],
"attachments": [],
"route": {
"locations": [],
"intermodals": [
{
"id": 461,
"sequence": 0,
"locations": [
{
"id": 1674,
"address": {},
"locationType": "POL",
"unlocode": "CNSHA",
"contact": {}
},
{
"id": 1675,
"address": {},
"locationType": "POD",
"unlocode": "AUSYD",
"contact": {}
}
],
"carriageType": "MAIN",
"vesselVoyage": {
"serviceCode": null,
"serviceName": null,
"voyageNumber": null,
"voyageNumberDirection": null,
"vesselCode": null,
"vesselLloydCode": null,
"vesselCallSign": null,
"vesselName": null,
"vesselCountryCode": null
}
}
],
"routeDates": {
"ReqDeliveryDate": null,
"FullReturnCutoff": null,
"VGMCutOffDate": null,
"DocumentCutOffDate": null,
"ArrivalAtFinalHub": null
}
},
"priceId": 1058870,
"quoteId": 92372
}
}
Update cargo terms
This endpoint is used to update the cargo terms for an existing booking.
HTTP Request
This endpoint only accepts PATCH requests, you must set Content-Type to application/json.
Dev
Live
Request Parameters
Example request
{
"containerLoad": "LCL",
"incoterm": "FOB",
"paymentMethod": "PREPAID"
}
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| JOB_ID | number | Y | The FreightExchange reference for the booking you are updating. |
| containerLoad | text | N | Type of load - acceptable values are FCL or LCL - full container load or less than container load. |
| incoterm | text | N | The incoterms to apply to the booking. See incoterms list above for valid values. |
| paymentMethod | text | N | The payment terms that apply. Acceptable values are PREPAID. |
Response Parameters
Example response
Parties
A container booking will typically have several parties linked to it. These can include the shipper, receiver, customer broker and any other parties who need to be notified or have an interest in the shipment. There are two endpoints that you can use to create or update these parties. They share the same structure but use a different request type. There are also additional endpoints to delete or retrieve a party.
HTTP request
The CREATE party endpoint accepts POST requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/party
Live “
The UPDATE party endpoint accepts PATCH requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/party/PARTY_ID
Live ”
The DELETE party endpoint accepts DELETE requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/party/PARTY_ID
Live “
The GET party endpoint accepts GET requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/party/PARTY_ID
Live ”
Request Parameters
Example request
{
"partyRoleCode": "NotifyParty",
"locationType": "NONE",
"partyName": "HELLO WORLD XXXX",
"address": {
"address2": "Address 2",
"city": "Melbourne",
"number": "1",
"postCode": "3000",
"state": "NSW",
"street": "Test Street",
"unit": "1"
},
"contact": {
"contactName": "Test Person",
"email": "test@test.com",
"fax": "090909090",
"phone": "04343879877"
},
"references": {
"COMPANY": "943"
}
}
| Field | Type | Mandatory | Description |
|---|---|---|---|
| JOB_ID | number | Y (when indicated) | The FreightExchange reference for the booking. |
| PARTY_ID | number | Y (when indicated) | The unique party ID being addressed. |
| partyRoleCode | text | Y | Identifier for the type of party - see list of party role codes above. |
| locationType | text | Y | NONE = not related to origin or destination, ORIGIN = origin party, DESTINATION = destination party |
| partyName | text | Y | Company name for the party |
| references | text | N | Can be used to specify that the address is taken from your address book |
| contact | N | Supplies contact details. See Contact definition. | |
| address | N | Supplies a full address for the party. See Address definition. |
Address Parameters
| Field | Type | Mandatory | Description |
|---|---|---|---|
| address2 | text | N | Second line of address |
| city | text | Y | City of address |
| countryCode | text | Y | ISO code for the country |
| number | text | N | Street number for the address |
| postCode | text | N | Post code for the address |
| state | text | N | State for the address |
| street | text | Y | Street address |
| unit | text | N | Unit number for the address |
Contact Parameters
| Field | Type | Mandatory | Description |
|---|---|---|---|
| contactName | text | N | Name of the contact |
| text | N | Contact email address | |
| fax | text | N | Fax number for contact |
| phone | text | N | Phone number for contact |
Response Parameters
Example response
{
"status": "Successful",
"result": {
"id": 1674,
"partyRoleCode": "NotifyParty",
"locationType": "NONE",
"references": {
"COMPANY": "943"
},
"address": {
"address2": "Address 2",
"city": "Melbourne",
"countryCode": "AU",
"number": "1",
"postCode": "3000",
"state": "NSW",
"street": "Test Street",
"unit": "1"
},
"contact": {
"email": "test@test.com",
"contactName": "Test Person",
"phone": "04343879877"
},
"partyName": "HELLO WORLD XXXX"
}
}
Also refer to the get booking endpoint for the overall response structure. The parties specific part reflects the request structure with the addition of the id field. This value must be used if you wish to use the update party endpoint.
Equipment
Equipment is equivalent to containers. Our API allows for many different characteristics of a container to be specified which may not be required in many applications.
HTTP request
The CREATE equipment endpoint accepts POST requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/equipment
Live “
The UPDATE equipment endpoint accepts PATCH requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/equipment/EQUIPMENT_ID
Live ”
The DELETE equipment endpoint accepts DELETE requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/equipment/EQUIPMENT_ID
Live “
The GET equipment endpoint accepts GET requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/equipment/EQUIPMENT_ID
Live ”
Request Parameters
Example request
{
"equipmentType": "2200",
"equipmentDates": {
"REQUESTED_PICKUP": "2019-10-01T00:00:00Z",
"EMPTY_EQUIPMENT_PLACEMENT": "2019-10-01T00:00:00Z",
"REQUESTED_DELIVERY": "2019-10-01T00:00:00Z",
"EMPTY_EQUIPMENT_RETURN": "2019-10-01T00:00:00Z"
},
"quantity": "1",
"socIndicator": false,
"references": {
"TEST_TEST": "Hello World"
},
"grossWeight": {
"unit": "KG",
"value": "12300.000"
},
"settings": {
"atmosphereType": "CA",
"co2Level": {
"value": "123"
},
"o2Level": {
"value": "11.22"
},
"dehumidity": {
"value": "111.22"
},
"preCooling": false,
"genSetType": "NR",
"sensitiveCargoDesc": "Hello World",
"temperature": {
"value": "123.22",
"unit": "C"
},
"ventilation": {
"value": "123.22",
"unit": "cm/h"
},
"ventSettingCode": "OPN10"
}
}
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| JOB_ID | number | Y (when indicated) | The FreightExchange reference for the booking. |
| EQUIPMENT_ID | number | Y (when indicated) | The equipment ID being addressed. |
| equipmentType | text | Y | The ISO container type. Refer to the container type list above. |
| equipmentDates | N | Refer to equipment dates below. | |
| quantity | number | Y | The number of containers. |
| socIndicator | boolean | N | |
| references | N | One of more references. Refer to references section. | |
| grossWeight | unit/value | Y | The gross weight of the container. Applicable values for unit are KG. |
| settings | N | Specialised settings for the container for items such as temperature control. Refer to equipment settings below. |
Equipment dates
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| REQUESTED_PICKUP | date | N | Date the loaded container will be collected. |
| EMPTY_EQUIPMENT_PLACEMENT | date | N | Date the empty container will be delivered. |
| REQUESTED_DELIVERY | date | N | Date the container will be delivered. |
| EMPTY_EQUIPMENT_RETURN | date | N | Date the empty container will be collected from the delivery point. |
Equipment settings
Note that these settings only need to be specified if your shipment specifically requires them. Setting these options can affect pricing and availability.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| atmosphereType | text | N | The atmosphere type. Applicable values are CA - controlled atmosphere, AFAM - advanced fresh air management, MA - modified atmosphere |
| co2Level | value | N | The CO2 level. No unit is required. |
| o2Level | value | N | The O2 level. No unit is required. |
| dehumidity | value | N | The dehumidity percentage. No unit is required. |
| preCooling | boolean | N | Indicates if pre-cooling is required. |
| genSetType | text | N | The generator type. Acceptable values are NR - not required, US - under slung, CO - clip on. |
| sensitiveCargoDesc | text | N | If the cargo is sensitive please supply a description. |
| temperature | value/unit | N | Desired temperatur. Acceptable values for unit are C, F. |
| ventilation | value/unit | N | The amount of ventilation required. Acceptable values for unit are cm/h. |
| ventSettingCode | text | N | The ventilation setting code. Acceptable values are listed in the ventilation setting codes above. |
Unit and value items
Within the equipment section some values are specified as a unit and value pair. These share a common structure where the numeric value and its unit of measure are specified in an object consisting of two fields: value and unit. The applicable values for unit depend on the field being set.
Response Parameters
Example response
{
"status": "Successful",
"result": {
"equipmentDates": {
"EMPTY_EQUIPMENT_PLACEMENT": "2019-10-01T00:00:00Z",
"REQUESTED_PICKUP": "2019-10-01T00:00:00Z",
"REQUESTED_DELIVERY": "2019-10-01T00:00:00Z",
"EMPTY_EQUIPMENT_RETURN": "2019-10-01T00:00:00Z"
},
"equipmentType": "2200",
"grossWeight": {
"value": 12300.0,
"unit": "KG"
},
"id": 576,
"locations": [],
"quantity": 1,
"references": {
"TEST_TEST": "Hello World"
},
"settings": {
"atmosphereType": "CA",
"co2Level": {
"value": 123.0
},
"dehumidity": {
"value": 111.22
},
"genSetType": "NR",
"o2Level": {
"value": 11.22
},
"preCooling": false,
"sensitiveCargoDesc": "Hello World",
"temperature": {
"value": 123.22
},
"ventilation": {
"value": 123.22,
"unit": "CM/H"
},
"ventSettingCode": "OPN10"
},
"socIndicator": false
}
}
Also refer to the get booking endpoint for the overall response structure. The equipment specific part reflects the request structure with the addition of the id field. This value must be used if you wish to use the update equipment endpoint.
Intermodals
Intermodal is equivalent to a leg, or part of a shipment. At present up to three intermodals can be added to a booking
HTTP request
The CREATE intermodal endpoint accepts POST requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/intermodal
Live “
The UPDATE intermodal endpoint accepts PATCH requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/intermodal/INTERMODAL_ID
Live ”
The DELETE intermodal endpoint accepts DELETE requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/intermodal/INTERMODAL_ID
Live “
The GET intermodal endpoint accepts GET requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/intermodal/INTERMODAL_ID
Live ”
Request Parameters
Example request
{
"references": {
"Hello": "World"
},
"sequence": 1,
"transportMode": "OCEAN",
"carriageType": "MAIN",
"locations": [
{
"locationType": "POL",
"locationName": "Hello World",
"unlocode": "CNYTN",
"references": {
"COMPANY": "943"
}
},
{
"locationType": "POD",
"locationName": "Hello World",
"unlocode": "AUSYD",
"references": {
"COMPANY": "943"
}
}
]
}
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| JOB_ID | number | Y | The FreightExchange reference for the booking. |
| INTERMODAL_ID | number | Y (if indicated) | The reference for the intermodal being addressed. |
| references | N | One of more references for the intermodal. Refer to the references section. | |
| sequence | number | N | Indicates the order of this intermodal. |
| transportMode | text | N | Indicates the mode of transport. |
| carriageType | text | N | Indicates the type of intermodal. Acceptable values are PRE - door to port, MAIN - port to port, POST - port to door. |
| locations | Y | Defines the locations associated with the intermodal. See the locations section below. | |
| vesselVoyage | N | Details of the voyage. This section is typically not included in requests but will be returned when you get details of a booking that has been confirmed. |
Locations
The locations section is populated in different ways depending on the intermodal being created. For port related legs it can be as simple as specifying the port (UNLOCODE) code. Alternatively a full address can be specified.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| locationType | text | Y | The type of location. Acceptable values are POL - port of loading, POD - port of discharge, FND - final destination, “ - . |
| locationName | text | N | A name of this location. |
| unlocode | text | N | The UNLOCODE for this location. |
| references | N | One or more references for this locations. See the references section. | |
| address | N | A full address for the location. See the address section. | |
| contact | N | Contact details for the location. See the contact section. |
Vessel voyage
This section is typically populated when the booking is confirmed with the carrier or forwarder. You will therefore receive values in this section when you retrieve a booking or intermodal section. These fields may not be populated in all circumstances depending on the information we receive from the carrier or forwarder.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| serviceCode | test | N | |
| serviceName | text | N | |
| voyageNumber | text | N | |
| voyageNumberDirection | text | N | |
| vesselCode | text | N | |
| vesselLloydCode | text | N | |
| vesselCallSign | text | N | |
| vesselName | text | N | |
| vesselCountryCode | text | N |
Response Parameters
Example response
{
"status": "Successful",
"result": {
"id": 465,
"sequence": 1,
"locations": [
{
"id": 1688,
"address": {},
"locationName": "Hello World",
"references": {
"COMPANY": "943"
},
"locationType": "POL",
"unlocode": "CNYTN",
"contact": {}
},
{
"id": 1689,
"address": {},
"locationName": "Hello World",
"references": {
"COMPANY": "943"
},
"locationType": "POD",
"unlocode": "AUSYD",
"contact": {}
}
],
"transportMode": "OCEAN",
"carriageType": "MAIN",
"vesselVoyage": {
"serviceCode": null,
"serviceName": null,
"voyageNumber": null,
"voyageNumberDirection": null,
"vesselCode": null,
"vesselLloydCode": null,
"vesselCallSign": null,
"vesselName": null,
"vesselCountryCode": null
},
"references": {
"Hello": "World"
}
}
}
The response follows the same structure as the request.
Cargo details
The cargo details section collected information about the commodities you are shipping - this is the contents of the container. This information is usually required for customs clearance to be carried out.
HTTP request
The CREATE cargo details endpoint accepts POST requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/cargodetail
Live ”
The UPDATE cargo details endpoint accepts PATCH requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/cargodetail/CARGO_DETAIL_ID
Live “
The DELETE cargo details endpoint accepts DELETE requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/cargodetail/CARGO_DETAIL_ID
Live ”
The GET cargo details endpoint accepts GET requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/cargodetail/CARGO_DETAIL_ID
Live “
Request Parameters
Example request
{
"cargoDescription": "Cargo Description",
"commodity": "Commodity",
"hsCodes": [
{
"code": "123.122.22.22"
}
],
"hazardousMaterial": [
{
"description": " Haz Description",
"imcoClass": "2.1",
"imcoPage": "1234",
"unNumber": "9876"
}
],
"dangerousGoods": true,
"height": {
"value": "1.23"
},
"length": {
"value": "1.23"
},
"width": {
"value": "1.23"
},
"netWeight": {
"value": "500"
},
"grossWeight": {
"value": "607"
},
"packingType": "Cartons",
"quantity": 10
}
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| JOB_ID | number | Y | The FreightExchange reference being addressed. |
| CARGO_DETAIL_ID | number | Y (when indicated) | The cargo detail ID being addressed. |
| cargoDescription | text | Y | A description of the goods being shipped. |
| commodity | text | N | The commodity of the goods being shipped. |
| hsCodes | array | N | One of more harmonized codes for the goods being shipped. Each code is represented in the structure shown in the example request. |
| hazardousMaterial | N | If the goods being shipped are considered hazardous/dangerous include this element. See hazardousMaterial section for details. | |
| dangerousGoods | boolean | Y | Indicates if the goods being shipped are dangerous goods. If you submit true for this value then a hazardousMaterial section should also be included. |
| length | number | N | The length in metres of the goods. This is to be represented in a value node as per the example request. |
| width | number | N | The width in metres of the goods. This is to be represented in a value node as per the example request. |
| height | number | N | The height in metres of the goods. This is to be represented in a value node as per the example request. |
| netWeight | number | N | The net weight in kilograms of the goods. This is to be represented in a value node as per the example request. |
| grossWeight | number | N | The gross weight in kilograms of the goods. This is to be represented in a value node as per the example request. |
| packingType | text | N | A description of the packaging type of the goods - for example carton or pallet. |
| quantity | number | N | The number of items described by this section being shipped. |
Hazardous material
This section is only required if the goods being shipped are considered hazardous.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| description | text | N | A description of the hazardous material. |
| imcoClass | text | N | The dangerous goods class. |
| imcoPage | text | N | The dangerous goods page. |
| unNumber | text | N | The UN number. |
Response parameters
Example response
{
"status": "Successful",
"result": {
"cargoDescription": "Cargo Description",
"commodity": "Commodity",
"dangerousGoods": true,
"grossWeight": {
"value": 607.0,
"unit": "KG"
},
"hazardousMaterial": [
{
"description": "Haz Description",
"imcoClass": "2.1",
"imcoPage": "1234",
"unNumber": "9876"
}
],
"height": {
"value": 1.23,
"unit": "M"
},
"hsCodes": [
{
"code": "123.122.22.22",
"countryCode": null
}
],
"id": 45,
"length": {
"value": 1.23,
"unit": "M"
},
"netWeight": {
"value": 500.0,
"unit": "KG"
},
"packingType": "Cartons",
"quantity": 10,
"references": null,
"width": {
"value": 1.23,
"unit": "M"
},
"equipments": null
}
}
The response follows the same structure as the request.
References
Throughout the booking APIs you have the opportunity to add references. Wherever references can be added they use the same structure which is a key/value pair. There are no limitations on the number of references you can add to a booking.
HTTP request
The CREATE reference endpoint accepts POST requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/references
Live ”
The UPDATE reference endpoint accepts PATCH requests, please set Content-Type to application/json.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/references/REFERENCE_KEY
Live “
The DELETE reference endpoint accepts DELETE requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/references/REFERENCE_KEY
Live ”
The GET reference endpoint accepts GET requests.
Dev https://apidemo.freightexchange.com.au/v2/booking/container/JOB_ID/references
Live “
Request parameters
Example request
{
"TEST" : "REFERENCE"
}
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| JOB_ID | number | Y | The FreightExchange reference being addressed. |
| REFERENCE_KEY | text | Y (if indicated) | The reference key being addressed. |
| KEY | text | Y | A key for the reference. |
| VALUE | text | Y | A value for the reference. |
Response parameters
Example response
{
"status": "Successful",
"result": {
"TEST": "REFERENCE"
}
}
The response follows the same structure as the request.
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.
Invoice reconciliation
Retrieve invoice totals
This endpoint will return summary details of all completed supplier invoices that have not previously been sent to your system. Only invoices relating to your own carrier accounts are available via this endpoint. It is the responsibility of your FreightExchange users to complete the invoice reconciliation process via the FreightExchange website - if invoices are not completed in that module they will not be available via this endpoint.
HTTP Request
This endpoint will only accept GET requests.
Dev https://apidemo.freightexchange.com.au/2.0/invoicereconciliation/completed?securityToken=SECURITY_TOKEN&updateTransferred=UPDATE_TRANSFERRED
Live https://api.freightexchange.com.au/2.0/invoicereconciliation/completed?securityToken=SECURITY_TOKEN
Request parameters
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| SECURITY_TOKEN | Text | Y | Your FreightExchange API security token |
| UPDATE_TRANSFERRED | Boolean | N | If you specify false for this parameter, we will not mark the returned invoices as downloaded. This means they will be included again on future requests to this endpoint. This parameter is primarily included for your testing purposes as it will allow to receive the same data on multiple occasions. We do not recommend sending false when using this endpoint in production. Note that you can exclude this paramter if you wish, which will result in the normal behaviour of the invoices being marked as downloaded. |
Response
Response paramaters
Example response
{
"vendorNumber" : "V00123",
"invoiceNumber" : "TEST1234",
"invoiceDate" : "2018-08-01",
"currency" : "AUD",
"details" : [
{
"identifier" : 1,
"description" : "TEST CARRIER",
"netAmount" : 1000
},
{
"identifier" : 2,
"description" : "TEST CARRIER",
"netAmount" : 200
}
]
}
The response from this API can consist of one or more header records, each of which can have two detail records.
Header record:
| Parameter | Type | Description |
|---|---|---|
| vendorNumber | text | Your identifier for the vendor to whom this invoice relates. |
| invoiceNumber | text | The vendor’s invoice number. |
| invoiceDate | date | The vendor’s invoice date. |
| currency | text | The three character ISO currency code for the amounts on this invoice. |
| details | node | The detailed amounts for this invoice. See definition below. |
Detail record:
| Parameter | Type | Description |
|---|---|---|
| identifier | number | Indicates the type of the amount in the detail record. 1 indicates that the amount is the total that was matched to expected costs. 2 indicates that the amount is the total that was not matched to expected costs (i.e. the variance). The sum of these two values will match the NET total of the invoice. |
| description | text | By default this will include the name of the vendor for the invoice. Please contact us to customise or exclude this field. |
| netAmount | number | The net amount for this detail line. |
Retrieve invoice documents
HTTP Request
This endpoint will only accept GET requests.
Dev https://apidemo.freightexchange.com.au/2.0/invoicereconciliation/document/DOCUMENT_TYPE?securityToken=SECURITY_TOKEN&invoiceNumber=INVOICE_NUMBER
Live https://api.freightexchange.com.au/2.0/invoicereconciliation/document/DOCUMENT_TYPE?securityToken=SECURITY_TOKEN&invoiceNumber=INVOICE_NUMBER
Request parameters
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| DOCUMENT_TYPE | Text | Y | Specifies the type of document to retrieve. TAXFILE will return the PDF of the vendor’s invoice. TRANSFILE will return the transaction file, typically a CSV that was received from the vendor and uploaded to the invoice reconciliation module. |
| SECURITY_TOKEN | Text | Y | Your FreightExchange API security token. |
| INVOICE_NUMBER | Text | Y | The vendor invoice number you wish to retrieve. |
Response
The endpoint will return the appropriate file in the HTTP response.
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 |
Webhooks
Introduction
We provide a number of webhooks which allow information to be pushed from FreightExchange to your systems. This is an alternative to you either waiting to processes to complete or having to regularly poll for updates. For these webhooks to work you must provide us with an endpoint that can accept POST requests in JSON format using the HTTPS protocol - please note that we do not support insecure HTTP requests.
In every case, your endpoint must return us a HTTP 200 response when you have successfully processed the request we sent. If we do not receive this response we will retry the request at 30 minute intervals for 7 days - i.e. a total of 336 times. If we have not received a 200 response after this time the message will be discarded and cannot be resent. Please bear in mind that if your endpoint is unavailable for a significant amount of time, you may receive a large number of requests from us when it becomes available again.
Tracking
If you have provided us with an endpoint URL we will send all tracking events as they are received. The message includes our unique job ID, the carrier’s tracking number as well as both shipperReference and shipperReference2 values to allow you to match the message to records on your systems.
For some carriers we are now able to supply a copy of the POD Signature as captured by the carrier. This information is typically supplied some time after the shipment is delivered and even for supported carriers may not be available for every shipment.
Response parameters
Example message
{
"id": 12003,
"jobId": 11825,
"shipperReference": "TEST ORDER",
"shipperReference2": "ANOTHER REFERENCE",
"shipperReference3" : "YET ANOTHER REFERENCE",
"eventCode": "PDU",
"eventDescription": "Picked-up",
"eventDateLocal": "2018-05-22 09:34:00",
"eventDateUTC": "2018-05-21 23:34:00",
"eventCity": "",
"eventPostCode": "",
"eventCountryCode": "",
"eventNotes": "",
"eventSignature": "",
"trackingNumber": "FGX000011825",
"securityToken" : "XXXXXXXXXXX",
"pod" : "POD_IMAGE_CONTENT"
}
We will push events to you in this format:
| Parameter | Type | Description |
|---|---|---|
| id | Number | Internal reference for the event |
| jobId | Number | FreightExchange reference for the shipment |
| shipperReference | Text | Your first reference for this shipment |
| shipperReference2 | Text | Your second reference for this shipment |
| shipperReference3 | Text | Your third reference for this shipment |
| 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) |
| trackingNumber | Text | The carrier’s tracking number for this shipment |
| securityToken | Text | Your security token which can be used to authenticate the request |
| pod | base64 | For POD events ONLY this field will include a base64 representation of an image of the receiver’s signature as supplied to us by the carrier |
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 |
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 |