Container Event Subscriptions API

Our API subscriptions provide users with an alternative to the email and XML-based notifications also provided by PortConnect for Container Visit and Vessel Schedule events. With our subscription model, users can choose to receive notifications via webhooks, email, or both, depending on their preferences. By subscribing to our API, users can stay up-to-date on important events and make informed decisions about their container logistics.

To receive callbacks for particular container events, you need to create a subscription by posting a request the subscriptions endpoint. Version 1 requests a single container visit event type code per request, Version 2 supports multiple container visit event type codes in a single request. Version 2 also supports the use of “ALL” to subscribe to all events for one or more containers.

Subscriptions can be created by Container Number or Booking Number.

Callbacks can be sent as emails to multiple email addresses, or as HTTP requests.

You must specify the uri location where you want the webhook callback to be sent, and optionally a token that you can use to verify the call. Other rules common to both versions are:

• Valid port codes are: NZAKL, NZTRG, NZTIU, NZLYT, DEPOT, ALL

• Valid category codes are: IMPORT, EXPORT, TRANSHIPMENT, DOMESTIC, STORAGE

• Facility codes are optional and relate to the port facility where the event takes place. If no facility code is specified, then webhook callbacks will be sent whenever the event occurs, regardless of the location.  For instance, if a subscription is created for an export "gate in", and the container is gated in to both an inland port and the sea port, then two gate in events will be sent as webhook callbacks.

• Only some event type codes support the use of the facility code, in all other cases a null value should be supplied.  Refer to the Notification Types.

• You can provide up to 10 container numbers or Booking numbers in each subscription request.

We permit one userDefinedReference per container, Booking or Vessel Reference. This is a maximum of 50 characters and is designed to support container visit and vessel schedule identifiers in calling systems.

The user defined reference will be included in the webhook callback payload against the specified container or Vessel Reference.

If you create a new subscription with a different user defined reference, it will overwrite the existing subscription including the user defined reference.

If you have already received events against the first subscription, you will receive future events against the new subscription with the new user defined reference.

• NZTIU - Timaru Container Terminal

• NZTRG - Port of Tauranga, Sulphur Point

• NZAKL - Port of Auckland 

• NZLYT - Lyttelton Port Company

• DEPOT - Empty depots. Excludes Port of Auckland LINK which is recorded under NZAKL

• ALL - This code covers ALL Port Codes

When creating subscriptions, containers may, or may not, be active in the PortConnect system.

If you create a subscription and there is an active container in the PortConnect system then the subscription will automatically link to the container and an initial callback will be sent which will include any subscribed events that may have already occurred. Additional callbacks will be sent as other subscribed events occur.

If you create a subscription and there is no active container in the PortConnect system then the subscription will remain in place for 90 days. If a container record with matching details (Port, Facility, Category) is created in our system then the subscription will link to the container and you will start receiving callbacks for the event types you have subscribed to.

When individual containers are added to a subscription they are created with an expiration date that is 90 days in the future. This allows users to add containers as soon as they are aware of them, which may be a long time before the port/PortConnect is aware of them.

Changing a reference on a container subscription will reset the 90 day window.

PortConnect sends callbacks when we find any subscriptions that have a matching Container/Category/Port combination and the subscription for the container has not expired. This means that if the same container visited a port as an import twice in the 90 day period then users would receive callbacks against both visits. If users do not wish to receive callbacks against the second visit then they can remove the container from the subscription once they are no longer interested in it (i.e. after the first visit gates out). Instructions on how to remove containers from subscriptions are below,

https://portconnect.atlassian.net/wiki/spaces/PUG/pages/2631237833

https://portconnect.atlassian.net/wiki/spaces/PUG/pages/2631237909

For every event callback received, users are eligible for one free call to the Container Visit API.

The standard fee for calling the Container Visit API is listed here. When preparing the monthly billing, PortConnect will discount one Container Visit API call for every event callback sent.