Ocean Booking Create

Allows customers to create a new ocean booking. Required fields are in bold text.

Access

To get access to this API, please fill in the Developer Registration form

Resource URI

Make an HTTP POST request to:

EnvironmentURL 
LIVE https://api.mainfreight.com/airandocean/1.0/ocean/booking?region={region}
UAT https://apitest.mainfreight.com/airandocean/1.0/ocean/booking?region={region}

Resource Information

TypeValue 
Authentication API Key  
Response Formats JSON / XML  
HTTP Methods POST  
API Version 1.0  

HTTP Headers

You must add the following HTTP Headers to your request:

HeaderDescriptionTypeRequired
Content-Type Request content type. Supported types are "application/json" or "application/xml" string Yes
Authorization

The word " Secret" followed by a space, then your unique API key

e.g: Secret wdnOId93-VXZECxvVRPQEJZNxPB5XZ...

 string Yes
Accept

Result content type. Supported types are "application/json" or "application/xml"

 string No

Parameters

You must provide the parameters marked as required:

 

HTTP Request Parameters

HeaderDescriptionTypeRequired
region

Region code, a list of available regions can be found on the Booking Reference List page 

 string Yes

Please note: This API currenly only supports NZ region

Request Body


FieldDescriptionTypeLengthRequired
account Account involved in the shipment object   Yes
code Related account code involved in the shipment (contact your local Air & Ocean representative to obtain this) string 6 Yes
serviceLevel An entity used to express the type of transportation object   Yes
code

Shorthand code to identify the service level

Options include: "STD" (standard), "HAZ" (hazardous), "PER" (perishable)

 string 3 Yes
containerMode

Shorthand code to identify the service level. Options include: "FCL", "LCL", "BCN"

 string 3 Yes
systemOfMeasurement

Indicates the system of measurement that applies to the shipment

Options include: "Metric", "Imperial"

 string 7 Yes
cargoReadyDateTime
   dateTime   No
port United Nations Location Codes relating to the Goods at either the Premise or Terminal object   Yes
origin UN/LOCODE of the location from which the freight is being shipped string 5 Yes
load UN/LOCODE of the first terminal where the freight will be loaded/paid up to string 5 No
discharge UN/LOCODE of the last terminal where the freight will be unloaded/paid up to string 5 No
destination UN/LOCODE of the destination in where the freight is going to string 5 Yes
origin Defines the origin or starting point of the shipment object   Yes 
sender Specifics of the origin shipper/consignor object   Yes
name Full name of the shipper/consignor  string 40 Yes
address1 Indicates a street name string 50 Yes
address2 Indicates other address identifiers string 50 No
postCode Indicates the postcode string 10 No
city Indicates the city string 30 Yes
state Indicates the state string 35 No 
countryCode 2 letter ISO code to identify the country string 2 No 
contact Indicates the origin sender contact object   Yes
name Name of the contact string 40 Yes
phone Phone number of the contact. Suggested format: +XX XXX XXXXXXX string 30 No
email Email address of the contact string 40 Yes
pickup Specifics of the pickup of the shipment (if required) object   No
name Full company name of the origin pickup string 40 Yes
address1 Indicates a street name string 50 Yes
address2 Indicates other address identifiers string 50 No
postCode Indicates the postcode string 10 No
city Indicates the city string 30 Yes
state Indicates the state string 35 No
countryCode 2 letter ISO code to identify the country string 2 No
contact Indicates the origin pickup contact object   Yes
name Name of the contact string  40 Yes
phone Phone number of the contact. Suggested format: +XX XXX XXXXXXX string  30 No
email Email address of the contact string  40 Yes
pickupTime Indicates origin pickup time information object    
fromDateTime Specifies the start of the pickup time window dateTime   No
toDateTime Specifies the end of the pickup time window dateTime   No
dropMode Indicates what type of pickup is required. If unsure use "STD" object    
code

Pickup drop mode. Pickup & Delivery Drop Modes can be found on the Booking Reference List page

 string 3 No
destination Defines the destination or ending point of the shipment object   Yes
receiver Defines the specifics of the destination consignee (if required) object   Yes
name Full company name for the delivery string 40 Yes
address1 Indicates a street name string 50 Yes
address2 Indicates other address identifiers string   No
postCode Indicates the postcode string 10 No
city Indicates the city string 30 Yes
state Indicates the state string 35 No
countryCode 2 letter ISO code to identify the country string 2 No
contact Indicates the destination receiver contact object   Yes
name Name of the contact string  40 Yes
phone Phone number of the contact. Suggested format: +XX XXX XXXXXXX string

 30

 No
email Email address of the contact string  40 Yes
delivery Defines the specifics of the delivery of the shipment (if required) object   No
name Full company name of the delivery address string 40 Yes
address1 Indicates a street name string 50 Yes
address2 Indicates other address identifiers string 50 No
postCode Indicates the postcode string 10 No
city Indicates the city string 30 Yes
state Indicates the state string 35 No
countryCode 2 letter ISO code to identify the country string 2 Yes
contact Indicates the destination delivery contact object   Yes
name Name of the contact string  40 Yes
phone Phone number of the contact. Suggested format: +XX XXX XXXXXXX string  30 No
email Email address of the contact object  40  Yes
deliveryTime

Indicates destination delivery time information for the receiver

 object   Yes
fromDateTime Specifies the start of the delivery time window dateTime   No
toDateTime Specifies the end of the delivery time window dateTime   No
dropMode Indicates what type of delivery is required. If unsure use "STD" object   No
code

Delivery drop mode. Pickup & Delivery Drop Modes can be found on the Booking Reference List page

 string 3  No
containers List of shipping containers for the shipment array   No
container Defines the shipping container information against a single container line object   No
containerNumber 11-character alphanumeric code comprising four letters and seven numbers, used to identify the shipping container number, against a single container Line string 11 No
commodityCode

Three-letter code to classify the type of goods being shipped

Options include: "GEN"

 string 4 No
containerCount

Number of shipping containers being booked against a container line (per container size)

 string 5

Yes, if container mode = FCL
containerType Defines the shipping container types object   No 
code Container type code. Container Types can be found on the Booking Reference List page string   Yes, if container mode = FCL
emptyReleaseNumber Provided by the carrier to the container terminal and booking party. Must be presented upon pick up at the terminal string 35  No
airVentFlow Defines ventilation of a shipping container against a single container line object   No
value Value of air vent flow  decimal  00000.0 Yes
unitOfMeasure

Unit of measure for air vent flow

Options include: "MQH", "2L", "P1"

 string  3  Yes
humidityPercent Required ideal humidity level inside a shipping container integer 3  No
setPointTemperature Defines temperature control value against a single goods line decimal 0.0 Yes, if using container type codes: "20REHC, "20REEFER", "40REHC", "40REEFER"
temperatureRecorderSerialNumber Data logger serial number of temperature monitoring and data recording device string 20 No
freightDetails Defines information about goods shipped on this shipment array   No
freightDetail Defines a single goods line of all goods on the shipment object   No
units Number of units on the freight line  integer 10 Yes
packTypeCode

A code that identifies the type of packaging used to prepare goods for transport. Pack Type codes can be found on the Booking Reference List page

 string 3 Yes
description Description of the goods on the freight line string 500 Yes
reference Customer feference of the goods on the freight line string 46 No
length Length (L) of goods on the freight line decimal 0.000 No
width Width (W) of goods on the freight line decimal 0.000 No
height Height (H) of goods on the freight line decimal 0.000 No
weight Weight of goods on the freight line decimal 0.000 No
volume Total volume of goods on the freight line, calculated using the formula length × width × height. This represents the space the goods occupy decimal 0.000 Yes, if LCL
commodityCode An three-letter code used to express the commodity of goods. Options include: "GEN", "HAZ", "PER" string 3 Yes
harmonisedCode A six-digit goods classification code defined by World Customs Organisation integer 6 No
temperatureControl Defines information about temperature control against a single cargo Line object   No
required  Indicates whether temperature control is required against a single container line boolean   No
minimum  Minimum container temperature of a single container line decimal 0.0 No
maximum  Maximum container temperature of a single container line decimal 0.0 No
dangerousGoodsLines List of dangerous goods lines array   No
dangerousGoodsLine Identification of a single line of materials or items with hazardous properties object   No
class Classification of DG Class string 4 Yes, if Commodity Code is HAZ
unNumber A four-digit code used to identify hazardous materials and articles integer 4 Yes, if Commodity Code is HAZ 
variant Identifies variant of the DG string 2 No
flashPoint Flashpoint of the DG in either Centigrade or Fahrenheit. Options include: "C" or "F" integer 4 No
packingGroup

Indicates the degree of danger associated with the DG. I is high danger and III is low danger. Options include: "I", "II", "III"

 string 3 No
commonName Identifies the common name string 150 Yes, if Commodity Code is HAZ 
references List of references against the shipment array   No
reference Indicates reference corresponding to the goods being shipped object   No
type Type of reference. Options include: "OrderReference" string  ∞ Yes
value Reference value. For OrderReference this relates to the entire booking. string  ∞ Yes
notes List of notes against the shipment array   No
note Details, notes or instructions for the shipment object   No
type Type of note. Options include: "ImportDeliveryInstructions", "ExportPickupInstructions", "SpecialInstructions", "BookingNotes" string   Yes
value Defines the instruction string   Yes
releaseType Indicates the Bill of Lading type to be issued object   Yes
code Release type code. Release Types can be found on the Booking Reference List page string 3 Yes
shipmentIncoTerm Defines the responsibilities, costs and risks of buyers and sellers for international transaction object   Yes
code

Specifies the international commercial term (Incoterm). Supported Inco Terms found on the Booking Reference List page

 string 3 Yes
insurance Identifies Insurance related information object   No
required Identifies if insurance is required boolean   No
value The amount stated to be the value of cover decimal 0.00 Yes, if required = true
currency Currency Code of the amount stated. Supported currency codes found on the Booking Reference List page string 3  Yes, if required = true

Response Body

FieldDescriptionTypeLength 
reference Booking reference identifier  string  ∞  

 

 

NOTE: Content in the panels below this point are not visible on the site unless used by other features e.g. gadgets, OB&E, etc.

Copyright © 2025