Create Vessel Schedule Subscriptions
- 1 Endpoint
- 2 Creating subscriptions
- 2.1 Partner ports
- 2.2 Vessels
- 2.2.1 Specific Vessels
- 2.2.2 User Defined Reference
- 2.3 Wharf Types
- 2.4 Event types
- 2.4.1 Single Event Type
- 2.4.2 Multiple Event Types
- 2.4.3 All Event Types
- 3 Example subscription
- 4 Example Response
- 5 Payload examples
Endpoint
POST https://api.portconnect.io/v1/subscriptions-vessel-schedule
Creating subscriptions
To receive vessel schedule event callbacks users must create subscriptions. Subscriptions can be created using the following filters:
Partner Port
Vessel
Wharf type aka Commercial type
Event type
Partner ports
NZWLG - Centreport Wellington
NZLYT - Lyttelton Port Company
NZAKL - Port of Auckland
NZTRG - Port of Tauranga
NZTIU - Timaru Container Terminal
Vessels
The vessels section in the subscription is not mandatory. If it is not included then the subscription will be created for all vessels.
Specific Vessels
Specific vessels can be included in the payload if desired. Vessels are identified by:
Port vessel reference or,
Lloyd/IMO number of the vessel
{
"vessels": [
{ "vesselRef": "KRJ3654"},
{ "lloydNumber": "9700524"},
{ "lloydNumber": "9188934"}
],
"webhookURI": "https://api.yourcompany.co.nz/webhooks/",
"webhookToken": "yoursecret",
"portCode": "NZTRG",
"wharfType": "Terminal"
}
User Defined Reference
Along with specifying vessels, users can also add user defined references. These references are not mandatory. The reference is saved at the vessel level.
{
"vessels": [
{ "vesselRef": "KRJ3654", "userDefinedReference":"TestRef"},
{ "lloydNumber": "9700524", "userDefinedReference":"TestRef2}
{ "lloydNumber": "9188934"}
],
"webhookURI": "https://api.yourcompany.co.nz/webhooks/",
"webhookToken": "yoursecret",
"portCode": "NZTRG",
"wharfType": "Terminal"
}
Wharf Types
Subscriptions can be filtered by wharf type. Wharf Type refers to the commercial type of the vessel and there are three options:
Terminal
Multicargo
Passenger
{
"portCode": "NZTRG",
"wharfType": "Terminal",
"emailAddressList": ["me@test.com"]
}
Event types
Subscriptions can be created for specific event types or all event types. A full list of event types is available here, Vessel Schedule Event Types.
Single Event Type
{
"vessels": [
{ "vesselRef": "MIA0001","userDefinedReference" : "MyReference"} ],
"webhookURI": "https://api.yourcompany.co.nz/webhooks/",
"webhookToken": "yoursecret",
"portCode": "NZTIU",
"emailAddressList": ["me@test.com"],
"wharfType": "Terminal",
"eventTypeCodes": ["VesselETAChanged"]
}
Multiple Event Types
{
"vessels": [
{ "vesselRef": "MIA0001","userDefinedReference" : "MyReference"} ],
"webhookURI": "https://api.yourcompany.co.nz/webhooks/",
"webhookToken": "yoursecret",
"portCode": "NZTIU",
"emailAddressList": ["me@test.com"],
"wharfType": "Terminal",
"eventTypeCodes": ["ReceivalCutOffInlandChanged","VesselETAChanged"]
}
All Event Types
{
"vessels": [
{ "vesselRef": "MIA0001","userDefinedReference" : "MyReference"} ],
"webhookURI": "https://api.yourcompany.co.nz/webhooks/",
"webhookToken": "yoursecret",
"portCode": "NZTIU",
"emailAddressList": ["me@test.com"],
"wharfType": "Terminal",
"eventTypeCodes": ["ALL"]
}
Example subscription
{
"vessels": [
{ "vesselRef": "KRJ3654", "userDefinedReference":"TestRef"},
{ "lloydNumber": "9700524"},
{ "lloydNumber": "9188934"}
],
"webhookURI": "https://api.yourcompany.co.nz/webhooks/", // Optional if emailAddressList is present
"webhookToken": "yoursecret", // Optional if emailAddressList is present
"emailAddressList": ["me@test.com"] // Optional if webhookURI and webhookToken are present
"portCode": "NZTRG",
"wharfType": "Terminal",
"eventTypeCodes": ["ReceivalCutOffInlandChanged","VesselETAChanged"]
}
Example Response
{
"subscriptionId": 88,
"vessels": [
{
"expirationDatetime": "2023-06-23T14:01:14.44+12:00",
"vesselRef": "KRJ3654",
"userDefinedReference": "MyReference"
},
{
"expirationDatetime": "2023-06-23T14:01:14.44+12:00",
"lloydNumber": 9700524
},
{
"expirationDatetime": "2023-06-23T14:01:14.44+12:00",
"lloydNumber": 9188934
}
],
"wharfType": "Terminal",
"eventTypeCodes": [
"VesselArrival",
"VesselDeparture",
"VesselCancelled",
"VesselETAChanged",
"VesselETDChanged",
"ReceivalCommenceInlandChanged",
"ReceivalCutOffInlandChanged",
"ReceivalCommenceSeaportChanged",
"ReceivalCutOffSeaportChanged"
],
"webhookURI": "https://api.yourcompany.co.nz/webhooks/",
"webhookToken": "yoursecret",
"emailAddressList": [
"me@test.com"
],
"portCode": "NZTRG"
}
Payload examples
© PortConnect 2026