V1 - Create Container Event Subscriptions
V1 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 1, a new subscription is created for every unique combination of:
PortCode, Category, FacilityCode and EventTypeCode.
If a subscription already exists for a particular combination then:
containers/bookings are added to that subscription
the emails are replaced
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.
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.
Endpoint
POST https://api.portconnect.io/v1/subscriptions
Request example using Container Numbers
Request Body with Container Numbers
"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",
"eventTypeCode": "AVAILABLE",
"facilityCode": null
{
"containers": [
{ "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 1"},
{ "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 2"},
{ "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3"}
],
}
Response Body with containers
{
"subscriptionId": 32,
"containers": [
{
"expirationDatetime": "2023-06-20T14:50:30.3+12:00",
"containerNumber": "TCNU8050683",
"userDefinedReference": "Azure Test 2",
"ClientCodes": []
}
]
}
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": "LOPReference1", "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",
"eventTypeCode": "AVAILABLE",
"facilityCode": null
}
Response Body with bookings
{
"subscriptionId": 32,
"bookings": [
{
"expirationDatetime": "2023-06-20T14:50:30.3+12:00",
"bookingNumber": "LOPReference1",
"userDefinedReference": "User Ref 1"
}
]
}
Client Codes
For software providers that represent multiple organisations, PortConnect allows API users to send through Client Codes per subscription container. Client Codes indicate which Trading Partner to bill for the relevant callbacks. This allows all API calls to come from a single source (the software provider) but for billing to go directly to the shipper.
When using Client Codes, a value must be provided in all subscriptions.
Request Body with Client Codes
"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",
"eventTypeCode": "AVAILABLE",
"facilityCode": null
{
"containers": [
{ "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 1", "clientCodes": ["ClientCode1"]},
{ "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 2", "clientCodes": ["ClientCode2"]},
{ "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3", "clientCodes": ["ClientCode3"]}
],
}
Response Body with containers
{
"subscriptionId": 32,
"containers": [
{
"expirationDatetime": "2023-06-20T14:50:30.3+12:00",
"containerNumber": "TCNU8050683",
"userDefinedReference": "Azure Test 2",
"clientCodes": ["ClientCode1"]
}
]
}
{
"subscriptionId": 32,
"containers": [
{
"expirationDatetime": "2023-06-20T14:50:30.3+12:00",
"containerNumber": "TCNU8050683",
"userDefinedReference": "Azure Test 2",
"clientCodes": ["ClientCode2"]
}
]
}
{
"subscriptionId": 32,
"containers": [
{
"expirationDatetime": "2023-06-20T14:50:30.3+12:00",
"containerNumber": "TCNU8050683",
"userDefinedReference": "Azure Test 2",
"clientCodes": ["ClientCode3"]
}
]
}