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 here

 string Yes

Please note: This API currenly only supports NZ region

Request Body


FieldDescriptionTypeLengthRequired
account   object   Yes
code Customer account number (org code) string 6 Yes
serviceLevel   object   Yes
code

Shorthand code to identify the service level.

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

 string 3 Yes
containerMode

 

Options include: "FCL", "LCL", "BCN"

 string 3 Yes
systemOfMeasurement

Indicates if the booking is using Metric or Imperial units

Options include: "Metric", "Imperial"

 string 7 Yes
cargoReadyDateTime
   dateTime   No
port   object   Yes
origin   string 5 Yes
load   string 5 No
discharge   string 5 No
destination   string 5 Yes
origin   object   Yes 
sender   object   Yes
name Full name of the contact 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/place string 30 Yes
state Indicates the state (where applicable) string 35 No 
countryCode Shorthand code to identify the country string 2 No 
contact   object   Yes
name   string 40 Yes
phone Contact phone number. Suggested format: +XX XXX XXXXXXX string 30 No
email   string 40 Yes
pickup   object   No
name Full name of the contact 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/place string 30 Yes
state Indicates the state (where applicable) string 35 No
countryCode Shorthand code to identify the country string 2 No
contact   object   Yes
name   string  40 Yes
phone Contact phone number. Suggested format: +XX XXX XXXXXXX string  30 No
email   string  40 Yes
pickupTime   object    
fromDateTime   dateTime   No
toDateTime   dateTime   No
pickupDropMode   object    
code

 Options include: "HSL", "HUL", "HWL", "PSL", "SDL", "STD", "TGT", "DDK", "EXU", "LOF", "SKL", "TIL", "TRL", "WUP"

 string 3 No
destination Defines the specifics of the ending point of the shipment object   Yes
receiver The party who physically receives the goods object   Yes
name Full name of the receiver string 40 Yes
address1   string 50 Yes
address2   string   No
postCode   string 10 No
city   string 30 Yes
state   string 35 No
countryCode Shorthand code to identify the country string 2 No
contact   object   Yes
name   string  40 Yes
phone Contact phone number. Suggested format: +XX XXX XXXXXXX string

 30

 No
email   string  40 Yes
delivery   object   No
name   string 40 Yes
address1   string 50 Yes
address2   string 50 No
postCode   string 10 No
city   string 30 Yes
state   string 35 No
countryCode   string 2 Yes
contact   object   Yes
name   string  40 Yes
phone Contact phone number. Suggested format: +XX XXX XXXXXXX string  30 No
email Email address of the contact object  40  Yes
deliveryTime

 

 object   Yes
fromDateTime   dateTime   No
toDateTime   dateTime   No
deliveryDropMode   object   No
code  Options include: "HSL", "HUL", "HWL", "PSL", "SDL", "STD", "TGT", "DDK", "EXU", "LOF", "SKL", "TIL", "TRL", "WUP" string 3  No
containers   array   No
containerNumber   string 11 No
commodityCode Options include: "GEN" string 4 No
containerCount

 

 string 5

Yes, if container mode = FCL
containerType   object   No 
code  

Options include: "BREAKBULK","RORO","20HW","20GPHR","20FLATRACK","20HT","20GP","20GPFG","20SOC","20GPTHERMA",

"20HCNORE","20HCSOC","20HCTHERMA","20HICUBE","20REHC","20HC","20HIGHWIDE","20ISO","","20NOR",

"20OPENTOP","20PWHIC","20PLATFORM","20REEFER","40HC45G1","40FLATRACK","40FRHC","40HT","40GP",

"40GPFG","40SOC","40GPTHERMA","40HCFG","40HCNORE","40HCSOC","40HCTHERMA","40HICUBE","40HIHARD",

"40REHC","40ISO","40NOR","40OPENTOP","40OPENHC","40PWHIC","40PLATFORM","40REEFER"

 string   Yes, if container mode = FCL
emptyReleaseNumber   string 35  No
airVentFlow   object   No
value    decimal  00000.0 Yes
unit  Options include: "MQH", "2L", "P1" string  3  Yes
humidityPercent   integer 3  No
setPointTemperature   object   No
value    decimal 0.0  Yes, if using container type code = refridgerated
unit  Options include: "C", "F" string 1 Yes
temperatureRecorderSerialNumber   string 20 No
freightDetails   array   No
units    integer 10 Yes
customerItemNumber   string 35 No
packTypeCode

Options include: "BAG","BLC","BAL","BSK","BI","BOT","BOX","BBK","BBG","BND","CAG","CTN","CAS","COI","CNT","CRD",

"CRT","CYL","DOZ","","DRM","ENV","GRS","KEG","MIX","PKG","PAI","PR","PLT","PCS","REL","ROL","SHT","SKD",

"SPL","TOT","TUB","UNT"

 string 3 Yes
description   string 500 Yes
reference   string 46 No
length   decimal 0.000 No
width   decimal 0.000 No
height   decimal 0.000 No
volume   decimal 0.000 Yes, if LCL
weightUnitOfMeasure Options include: "LB", "KG" string 3  Yes
volumeUnitOfMeasure Options include: "FT3", "M3" string 3  Yes, if volume present
commodityCode Options include: "GEN", "HAZ", "PER" string 3 Yes
harmonisedCode   integer 6 No
temperatureControl   object   No
required   boolean    Yes, if Commodity Code = PER
minimum   decimal 0.0  Yes, if Commodity Code = PER 
maximum   decimal 0.0  Yes, if Commodity Code = PER 
unit Options include: "C", "F" string  1   Yes, if Commodity Code = PER
dangerousGoodsLines   object   No
class   string 4 Yes, if Commodity Code is HAZ
unNumber   integer 4 Yes, if Commodity Code is HAZ 
variant   string 2 No
flashPoint   integer 4 No
packingGroup Options include: "I", "II", "III" string 3 No
commonName   string 150 Yes, if Commodity Code is HAZ 
references   array   No
type Options include: "OrderReference" string  ∞ Yes
value   string  ∞ Yes
notes   array   No
type Options include: "ImportDeliveryInstructions", "ExportPickupInstructions", "SpecialInstructions", "BookingNotes" string   Yes
value   string   Yes
releaseType   object   Yes
code Options include: "EBL", "BRR", "OBD", "OBR", "SWB" string 3 Yes
shipmentIncoTerm   object   Yes
code  Options include: "FOB", "CFR", "CIF", "CPT", "DAP", "DAT", "DDP", "DPU", "EXW", "FAS", "FOB", "FCA" string 3 Yes
insurance   object   No
required   boolean   No
value   decimal 0.00 Yes, if required = true
currency   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