Excerpt

hidden	true

POST /v1/export-preadvices

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.

Endpoint

Code Block
POST https://api.portconnect.io/v1/export-preadvices

Request Body

...

Name

...

Type

...

Description

...

header

...

PreadviceHeader

...

Pre-advice header information

...

containers

...

PreadviceContainer[]

...

List of container information

...

comments

...

string (optional)

...

Additional comments (not included in Swagger documentation)

PreadviceHeader

...

Name

...

Type

...

Description

...

Required

...

Notes

...

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

...

Table of Contents

style	none

API Request Body

Header section

Level	Name	Required	Repeats	Type	Description	Applicable Ports
0	header	PreadviceHeader	No	-	Pre-advice header information
1	shipperName	Mandatory	No	string	Shipper name	ALL
1	consigneeName	Optional	No	string	Consignee name	NZTRG / NZTIU
1	bookingReference	Mandatory	No	string	Booking reference	ALL
1	messageAction	Mandatory	No	string (Create/Cancel)	For new Pre-Advice or updates to previously submitted containers enter “Create”. To Cancel a previously submitted incorrect container number enter "Cancel".	ALL
1	pointOfOriginCode	Mandatory	No	string	Point of origin code	ALL
1	loadPortFacility	Mandatory	No	string	Load port facility	ALL
1	vessel	Mandatory

Vessel

GenericPreadviceVessel

No

Vessel information

ALL

Mandatory

2

shipName

Conditional

No

string

Vessel Name

ALL

Optional

2

voyageNumber

Conditional

No

string

Voyage Number

Optional

ALL
2	partnerPortShippingReference	Conditional	No	string	Port Vessel reference

Optional

ALL

NotificationEmails

1

string[]

List of notification email addresses

lineOperatorCode

Mandatory

UserName

No

string

User name

Mandatory

UserReference

string

User reference

Mandatory

LineOperatorCode

string

Line operator code

Mandatory

LoadPortCode

string

Line operator code	ALL
1	loadPortCode	Mandatory	No	string	Load port code

Mandatory

ALL

PortOfDischarge

1

string

portOfDischarge

Port of discharge

Mandatory

ForeignPortOfDischarge

Optional

No

string

Foreign port

Port of discharge

Optional

OverseasDestinationFinal

string

Overseas destination final

Optional

PreadviceContainer

...

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:

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

Example Messages

All fields example:

Code Block

language	json

    "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

Code Block

language	json

{
	"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:

...

language	json

...

. If the segment is omitted then PortConnect will look up and populate the value from the booking.	ALL
1	foreignPortOfDischarge	Optional	No	string	Foreign port of discharge	ALL
1	overseasDestinationFinal	Optional	No	string	Overseas destination final	ALL
1	notificationEmails	Mandatory	No	string[]	List of notification email addresses	ALL
1	userName	Mandatory	No	string	User name	ALL
1	userReference	Mandatory	No	string	User reference	ALL

Container section

Level	Name	Required	Repeats	Type	Description	Applicable Ports
0	containers	Mandatory	Yes	List of container information		ALL
1	containerNumber	Mandatory	No	string	Container number	ALL
1	attachedContainerNumbers	Optional	No	string[]	List of attached container numbers. Only required if the container has attached containers.	NZTRG / NZTIU
1	isoTypeCode	Mandatory	No	string	ISO type code for the container	ALL
1	flexiTank	Optional	No	bool	Indicates if the container is a flexi tank	NZTRG / NZTIU
1	isFull	Mandatory	No	bool	Indicates if the container is full	ALL
1	commodityCode	Mandatory	No	string	Commodity code	ALL
1	isNonOperatingReefer	Optional	No	bool	Indicates if the container is a non-operating reefer. Only required if container ISO Type is a Reefer ISO type.	ALL
1	refrigeration	Optional	No		Refrigeration details for the container. Only required if container ISO Type is a Reefer ISO type.	ALL
2	isFantainer	Optional	No	bool		ALL
2	requiredTemperature	Conditional	No	float		ALL
2	refrigerationType	Optional	No	string	“Chilled”	ALL
2	activeRefrigerationRequired	Conditional				NZTRG
2	offPowerTemperature	Optional	No	float		NZAKL
2	offPowerTimestamp	Optional	No	DateTime		NZAKL
2	onPowerTargetTime	Optional	No	DateTime		NZAKL
2	humidityPercent	Optional	No	float		ALL
2	co2Percent	Optional	No	float		ALL
2	o2Percent	Optional	No	float		ALL
1	vent	Optional	No		Vent details for the container	ALL
2	ventSettingType	Optional	No	string		ALL
2	ventSetting	Optional	No	float		ALL
1	cargoWeightKg	Mandatory	No	float	Cargo weight in kilograms	ALL
1	totalWeightKg	Mandatory	No	float	Total weight of the container in kilograms	ALL
1	hazardous	Optional	No		List of hazardous details	ALL
2	hazardousClass	Conditional	Yes	float	e.g. 1.1f, 1.1g etc.	ALL
2	unNumber	Conditional	Yes	string	e.g. 0005, 0121 etc	ALL
2	quantity	Conditional	Yes	string	Number and Type of packages e.g. 2 Pallets or 1 box	ALL
2	hazardousWeight	Conditional	Yes	float	Weight of the hazardous cargo. Must be in KGs.	ALL
2	packagingGroup	Conditional	Yes	string	Values: 0, 1, 2 or 3. If no packaging group then select 0.	ALL
2	limitedQuantities	Conditional	Yes	bool		ALL
2	marinePollutant	Conditional	Yes	bool		ALL
2	emsCode	Conditional	Yes	string	Fire Rating and Spill Rating. F-A to F-Z and S-A to S-Z. No space between values.	ALL
2	hazardContact	Conditional	Yes			ALL
3	name	Conditional	Yes	string		ALL
3	phone	Conditional	Yes	string		ALL
2	medicalFirstAidGuideSet	Conditional	Yes	string		NZTRG / NZTIU
2	flashPointSet	Conditional	Yes	float	Range: -999-999	NZTRG / NZTIU
1	overGauge	Optional	No	GenericPreadviceOverDimension[]	List of over-dimension details. Only required if container ISO Type is an Out of Gauge ISO type.	ALL
2	area	Conditional	Yes	String	TOP, LEFT, RIGHT, FRONT, BACK	ALL
2	measureCm	Conditional	Yes	float		ALL
1	containerSeals	Mandatory	No	GenericPreadviceContainerSeal[]	List of container seals	ALL
2	sealType	Mandatory	Yes	string		ALL
2	sealCode	Mandatory	Yes	string		ALL
1	arrivalCarrierType	Mandatory	No	string	Value list: Truck, Rail. This is the mode of arrival at the receival facility which can be an inland port or directly to the Seaport	ALL
1	carrier	Mandatory	No	string	See the following list for all Arrival Carrier Codes.	ALL
1	hazardousCertificateBase64	Optional	No	string	Base64 encoded hazardous certificate. Only required if the container is hazardous. The base64 content must sit within a CDATA segment e.g. “hazardousCertificateBase64”: <![CDATA[Base64ContentHere]]>	NZTRG / NZTIU

Test URL:

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

Example Messages

All fields example:

Code Block

language	json

    {
	"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": ["info@portconnect.co.nz"]
	},
	"containers": [{
		"containerNumber": "HAZD1234510"	
		"isoTypeCode": "4500",
		"isFull": true,
		"commodityCode": "74",
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"hazardous": [{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.1",
			"unNumber": "1950",
			"packagingGroup": "1",
			"limitedQuantities": true,
			"marinePollutant": true,
			"hazardousWeight": 200.0,
			"quantity": "10",
			"emsCode": "F-BS-C",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 588 998"
			}
		},
		{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.2",
			"unNumber": "1950",
			"packagingGroup": "0",
			"limitedQuantities": false,
			"marinePollutant": false,
			"hazardousWeight": 1000.0,
			"quantity": "75",
			"emsCode": "F-YS-Y",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 588 998"
			}
		}],
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "4455"
		}],
		"arrivalCarrierType": "Rail",
		"carrier": "CONLIN"
	},
	{
		"containerNumber": "OOGC1234651"	
		"attachedContainerNumbers": ["ADCU1234510"],
		"isoTypeCode": "22P1",
		"isFull": true,
		"commodityCode": "47",
		"isNonOperatingReefer": false,
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"overGauge": [{
			"area": "Top",
			"measureCm": 10.0
		},
		{
			"area": "Left",
			"measureCm": 20.0
		},
		{
			"area": "Right",
			"measureCm": 30.0
		},
		{
			"area": "Front",
			"measureCm": 40.0
		},
		{
			"area": "Back",
			"measureCm": 50.0
		}],
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "TBC"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "AACAR "
	},
	{
		"containerNumber": "REEF1234510"		
		"isoTypeCode": "2230",
		"isFull": true,
		"commodityCode": "2199",
		"IsNonOperatingReefer": false,
		"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,
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "1223"
		},
		{
			"sealType": "Shipper",
			"sealCode": "5665"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "WALTER"
	}]
}

Hazard example

Code Block

language	json

{
	"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": ["info@portconnect.co.nz"]
	},
	"containers": [{
		"containerNumber": "REEF1234510",
		"isoTypeCode": "2230",
		"isFull": true,
		"commodityCode": "2199",
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"hazardous": [{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.1",
			"unNumber": "1950",
			"packagingGroup": "1",
			"limitedQuantities": true,
			"marinePollutant": true,
			"hazardousWeight": 200.0,
			"quantity": "10",
			"emsCode": "F-BS-C",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 588 998"
			}
		},
		{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.2",
			"unNumber": "1950",
			"packagingGroup": "0",
			"limitedQuantities": false,
			"marinePollutant": false,
			"hazardousWeight": 1000.0,
			"quantity": "75",
			"emsCode": "F-YS-Y",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 588 998"
			}
		}],
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "1223"
		},
		{
			"sealType": "Shipper",
			"sealCode": "5665"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "WALTER",
		"hazardousCertificateBase64":<![CDATA[JVBERi0xLjcNDQo8PC9UNQ0KJSVFT0Y=]]>
	}]
}

Reefer example

Code Block

language	json

{
	"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": ["info@portconnect.co.nz"]
	},
	"containers": [{
		"containerNumber": "REEF1234510",
		"isoTypeCode": "2230",
		"isFull": true,
		"commodityCode": "2199",
		"IsNonOperatingReefer": false,
		"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,
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "1223"
		},
		{
			"sealType": "Shipper",
			"sealCode": "5665"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "WALTER"
	}]
}

Example Response:

Export pre-advice success

...

Versions Compared

Old Version 6

New Version Current

Key

Endpoint

Request Body

PreadviceHeader

API Request Body

Header section

PreadviceContainer

Test URL:

Example Messages

All fields example:

Reefer / Hazard example

Example Request Body short:

Container section

Test URL:

Example Messages

All fields example:

Hazard example

Reefer example

Example Response:

Export pre-advice success

Page Comparison

Versions Compared

Old Version 6

New Version Current

Key

Endpoint

Request Body

PreadviceHeader

API Request Body

Header section

PreadviceContainer

Test URL:

Example Messages

All fields example:

Reefer / Hazard example

Example Request Body short:

Container section

Test URL:

Example Messages

All fields example:

Hazard example

Reefer example

Example Response:

Export pre-advice success