V2 Summary

To receive callbacks for particular container events, you need to create a subscription by POSTing to the subscriptions endpoint.

Subscriptions can be created by Container Number or Booking Number.

For version 2, a new subscription is created for every unique combination of:

PortCode, Category and FacilityCode. 

Callbacks can be sent as emails to multiple email addresses, or as HTTP requests. When creating the subscription you must pass either WebhookURI and WebhookToken or an EmailAddressList.

For the eventTypeCodes we allow for more than 10 event types to be specified in the subscription request. Users can also use the "ALL" to subscribe to all event types.

V1 vs V2 differences

Version 1 allows 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.

Event Types are applied to all containers associated to the subscription

V2 Subscriptions are created based on PortCode, Category and Facility Code. POSTs are an Add action rather than a Replace action and any event types included will be applied to all containers currently linked to the subscription i.e. if you send two subscription POSTs with the same Port/Category/Facility but with different containers and different event types then the event types from both POSTs will be linked to the subscription and all containers associated with the subscription will receive event callbacks for the full list of event types associated with the booking.

If you want to reduce the number of events associated with a Subscription then there are three ways to do this:

1. Delete the whole subscription and re-add all containers.

2. Delete all individual containers from the subscription and re-add them.

3. Reduce the number events in the POST and wait for up to 90days for older containers to be removed from the subscription.

Endpoint

POST https://api.portconnect.io/v2/subscriptions

Request Body with Container Numbers

{
  "containers": [
    { "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 1"},
    { "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 2"},
    { "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3"}
  ],
  "webhookURI": "https://api.yourcompany.co.nz/webhooks/portconnect", // 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",
  "category": "IMPORT",
  "eventTypeCodes": ["ALL", "Discharge"],
  "facilityCode": null
}

Response Body with containers:

{
    "subscriptionId": 32,
    "containers": [
        {
            "expirationDatetime": "2023-06-20T14:50:30.3+12:00",
            "containerNumber": "TCNU8050683",
            "userDefinedReference": "Azure Test 2"
        }
    ]
}

Request example using Booking Numbers

When creating a subscription against a Booking Number, callbacks will be sent for any Export containers with the specified booking number.

Request Body with Booking Numbers

{
  "bookings": [
    { "bookingNumber": "LOPReferenc1", "userDefinedReference" : "User ref 1"}
  ],
  "webhookURI": "https://api.yourcompany.co.nz/webhooks/portconnect", // 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",
  "category": "EXPORT",
  "eventTypeCodes": ["ALL", "Load"],
  "facilityCode": null
}

Response Body with bookings:

{
    "subscriptionId": 32,
    "bookings": [
        {
            "expirationDatetime": "2023-06-20T14:50:30.3+12:00",
            "bookingNumber": "LOPReferenc1",
            "userDefinedReference": "User ref 12"
        }
    ]
}