In order to understand the Export Pre-advice submission, some familiarity with the Export Pre-advice User Guide is recommended. This details how export pre-advice submitted via the PortConnect website. The structure of the API is conceptually very similar to this screen, comprising a header with a list of containers being submitted.

API Request Body

Name	Type	Description
header	PreadviceHeader	Pre-advice header information
containers	PreadviceContainer[]	List of container information

Header section

Name	Type	Description	Required
ShipperName	string	Shipper name	Mandatory
ConsigneeName	string	Consignee name	Optional
BookingReference	string	Booking reference	Mandatory
MessageAction	string (Create/Cancel)	Message action type	Mandatory
PointOfOriginCode	string	Point of origin code	Mandatory
LoadPortFacility	string	Load port facility	Mandatory
Vessel	GenericPreadviceVessel	Vessel information	Mandatory
shipName	string	Vessel Name	Optional
voyageNumber	string	Voyage Number	Optional
partnerPortShippingReference	string	Port Vessel reference	Optional
NotificationEmails	string[]	List of notification email addresses	Mandatory
UserName	string	User name	Mandatory
UserReference	string	User reference	Mandatory
LineOperatorCode	string	Line operator code	Mandatory
LoadPortCode	string	Load port code	Mandatory
PortOfDischarge	string	Port of discharge	Mandatory
ForeignPortOfDischarge	string	Foreign port of discharge	Optional
OverseasDestinationFinal	string	Overseas destination final	Optional

Container section

Name	Type	Description	Required	Notes
HazardousCertificateBase64	string	Base64 encoded hazardous certficate	Optional
LatestSubmissionStatus	GenericPreadviceContainerSubmission	Latest submission status of the container	Optional
CurrentStatus	string	Current status of the container	Optional
ContainerNumber	string	Container number	Mandatory
AttachedContainerNumbers	List<string>	List of attached container numbers	Optional
IsoTypeCode	string	ISO type code for the container	Mandatory
FlexiTank	bool?	Indicates if the container is a flexi tank	Optional
IsFull	bool?	Indicates if the container is full	Mandatory
CommodityCode	string	Commodity code	Mandatory
IsNonOperatingReefer	bool?	Indicates if the container is a non-operating reefer	Optional
Refrigeration	GenericPreadviceRefrigeration	Refrigeration details for the container	Optional	Only required if container ISO Type is a Reefer ISO type
isFantainer	bool?		Optional
requiredTemperature	float		Optional
refrigerationType	string		Optional
humidityPercent			Optional
RefrigerationType	string (chilled)		Optional
Vent	GenericPreadviceVent	Vent details for the container	Optional
ventSettingType			Optional
ventSetting			Optional
IMEX	GenericPreadviceIMEX	IMEX details for the container	Mandatory
CargoWeightKg	float	Cargo weight in kilograms	Mandatory
TotalWeightKg	float	Total weight of the container in kilograms	Mandatory
Hazardous	GenericPreadviceHazardous[]	List of hazardous details	Optional
			Optional
			Optional
			Optional
			Optional
			Optional
OverGauge	GenericPreadviceOverDimension[]	List of over-dimension details
ContainerSeals	GenericPreadviceContainerSeal[]	List of container seals	Mandatory
sealType	string (required)		Mandatory
sealCode	string (required)		Mandatory
ArrivalCarrierType	GenericPreadviceArrivalCarrierTypes?	Arrival carrier type	Mandatory
Carrier	string	Carrier details	Mandatory

Test URL:

POST https://apitest.portconnect.io/v1/export-preadvices

Example Messages

All fields example:

    "header": {
        "shipperName": "ABB HENDERSON",
        "bookingReference": "ACD0524204",
        "pointOfOriginCode": "Auckland",
        "loadPortFacility": "TCT",
        "vessel": {
            "shipName": "NEFELI",
            "voyageNumber": "2116",
            "partnerPortShippingReference": "FEL2116"
        },
        "partnerPortCode": "NZTRG",
        "userName": "test-preadvice-portconnect-co-nz",
        "userReference": "POT_TEST1",
        "lineOperatorCode": "ANNU",
        "loadPortCode": "NZTRG",
        "portOfDischarge": "AUSYD",
        "foreignPortOfDischarge": "AUMEL"
    },
    "containers": [
            {
      "ContainerNumber": "XONU1234520",
      "IsoTypeCode": "2200",
      "FlexiTank": false,
      "IsFull": true,
      "CommodityCode": "01",
      "IsNonOperatingReefer": false,
      "IMEX": {
        "CustomsClearanceNumber": "",
        "ExportEntryNumber": ""
      },
      "CargoWeightKg": 8000.0,
      "TotalWeightKg": 10000.0,
      "HazardContact": {
        
      },
      "Hazardous": [
        
      ],
      "OverGauge": [
        
      ],
      "ContainerSeals": [
        {
          "SealType": "Shipper",
          "SealCode": "hghghg"
        }
      ],
      "ArrivalCarrierType": "Truck"
    },
    {
      "ContainerNumber": "CONU1234560",
      "IsoTypeCode": "2030",
      "FlexiTank": false,
      "IsFull": true,
      "CommodityCode": "2199",
      "IsNonOperatingReefer": false,
      "Refrigeration": {
        "IsFantainer": false,
        "Co2Percent": 55.0,
        "O2Percent": 34.0,
        "TimeAllowedOffPowerHours": 3,
        "TimeAllowedOffPowerMinutes": 2,
        "ActiveRefrigerationRequired": true,
        "RequiredTemperature": 5.0,
        "HumidityPercent": 78.0,
        "RefrigerationType": 1
      },
      "Vent": {
        "VentSettingType": "PercentageOpen",
        "VentSetting": 3.0
      },
      "IMEX": {
        "CustomsClearanceNumber": "",
        "ExportEntryNumber": ""
      },
      "CargoWeightKg": 8000.0,
      "TotalWeightKg": 10000.0,
      "HazardContact": {
        
      },
      "Hazardous": [
        
      ],
      "OverGauge": [
        
      ],
      "ContainerSeals": [
        {
          "SealType": "Shipper",
          "SealCode": "aaaaa"
        },
        {
          "SealType": "Shipper",
          "SealCode": "bbbbbbbbb"
        },
        {
          "SealType": "Shipper",
          "SealCode": "cccccccc"
        }
      ],
      "ArrivalCarrierType": "Truck"
    }
    ]
}'

Reefer / Hazard example

{
	"header": {
		"shipperName": "FNT",
		"loadPortCode": "NZAKL",
		"bookingReference": "SHIPPINGLINEBOOKINGREF",
		"pointOfOriginCode": "AKC",
		"vessel": {
			"shipName": "CMA CGM SEMARANG",
			"voyageNumber": "2416",
			"partnerPortShippingReference": "CMC9741"
		},
		"loadPortFacility": "Auckland",
		"lineOperatorCode": "ARMC",
		"portOfDischarge": "AUMEL",
		"foreignPortOfDischarge": "AUMEL",
		"userReference": "UNIQUEREFERENCE",
		"notificationEmails": ["chris.boxall@portconnect.co.nz"]
	},
	"containers": [{
		"containerNumber": "REEF1234510",
		"attachedContainerNumbers": [],
		"isoTypeCode": "2230",
		"isFull": true,
		"commodityCode": "2199",
		"refrigeration": {
			"isFantainer": false,
			"co2Percent": 50.0,
			"o2Percent": 40.0,
			"maximumOffPowerHours": 24.0,
			"offPowerTemperature": -21.0,
			"offPowerTimestamp": "2024-09-11T10:00:00+12:00",
			"onPowerTargetTime": "2024-09-11T10:00:00+12:00",
			"requiredTemperature": -21.0,
			"humidityPercent": 20.0,
			"refrigerationType": "Chilled"
		},
		"vent": {
			"ventSettingType": "PercentageOpen",
			"ventSetting": 30.0
		},
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"hazardous": [{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.1",
			"unNumber": "1950",
			"packagingGroup": "1",
			"limitedQuantities": true,
			"marinePollutant": false,
			"hazardousWeight": 200.0,
			"quantity": "20",
			"emsCode": "F-AS-B",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 345 678"
			}
		}],
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "1223"
		},
		{
			"sealType": "Shipper",
			"sealCode": "5665"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "WALTER"
	}]
}

Example Request Body short:

{
  "header": {
    "shipperName": "ALNEMAH HALAL MEAT LIMITED",
    "bookingReference": "1AKL026740",
    "lineOperatorCode": "HSUD",
    "loadPortCode": "NZTRG",
    "portOfDischarge": "USLGB",
    "foreignPortOfDischarge": "USLGB"
    "pointOfOriginCode": "Bay of Plenty",
    "loadPortFacility": "TCT",
    "vessel": {
      "shipName": "DEBUSSY",
      "voyageNumber": "138N",
      "partnerPortShippingReference": "USY138N",
    },
    "notificationEmails": [
      "Cameron.Pitches@portconnect.co.nz"
    ],
    "userReference": "CAMTEST001"
  },
  "containers": [
    {
      "containerNumber": "CDPU3736837",
      "isoTypeCode": "2200",
      "flexiTank": false,
      "isFull": true,
      "commodityCode": "0201"
      },
      "cargoWeightKg": 28000.0,
      "totalWeightKg": 30000.0,
      "containerSeals": [
        {
          "sealType": "Shipper",
          "sealCode": "555"
        }
      ],
      "arrivalCarrierType": "Truck"
    }
  ]
}

Example Response:

Export pre-advice success

{
    "success": true,
    "errors": [],
    "containers": [
        {
            "containerNumber": "CDPU3736837",
            "errors": [],
            "success": true
        }
    ]
}

However, should the requiredTemperature value be set to -50 in the example above, then the following is returned:

Export pre-advice partial failure

{
    "success": true,
    "errors": [],
    "containers": [
        {
            "containerNumber": "CDPU3736837",
            "errors": [
                "Temperature too high/low for the selected commodity (Range: -5.0 to 2.0). Change commodity or contact Terminal"
            ],
            "success": false
        }
    ]
}

Pre-Advice validation rules

Must provide a valid booking
Load Port must match the booking
Load Port must be valid
Line Operator code must be valid
Line Operator code must match the booking
Vessel Visit must match the booking
Discharge Port must match the booking
Reefer ISO type containers must have a Temperature (unless specified as a Non-Operating Reefer)
Freight Kind (Full vs Empty) must match the booking
Reefer temperatures must match the booking
Conditioning details must match the booking. Conditioning details include: Humidity %, Vent value, Vent Type, O2% and CO2%
Hazard UN Codes must match the booking
Container ISO Type Groups much match the booking.
Total Pre-Advised Containers must not exceed the booking quanta (count)
Seal Type must be valid

Submit Export Pre-advice