Create Zone & Port Notification Subscription

Production

https://api.polestar-production.com

POST

/notifications/v1/zones-and-ports

Subscribe to events for an area. Part of both Port & Trade and
Domain & Fleet.

List the zones or ports to monitor in settings.filters.zones_ports in the
request body. See the guides for your package for how to find the right
identifier.

Choose the events in settings.filters.event_types: ZONE_ENTRY,
ZONE_EXIT, PORT_AREA_ARRIVAL, PORT_AREA_DEPARTURE, PORT_ARRIVAL,
PORT_DEPARTURE, BERTH_ARRIVAL and BERTH_DEPARTURE come from observed
movements. NEW_INBOUND (a vessel reports a watched port as its
destination) and ETA_CHANGE (an inbound vessel changes its reported ETA)
come from what the vessel reports about itself.

Request

Authorization

API Key

Add parameter in header

api-key

Example:

api-key: ********************

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

Zone and port notification subscription created. Returns the new zone and port notification subscription.

Headers

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠409

🟠422Parameter Error

🔴500Server Error

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.polestar-production.com/notifications/v1/zones-and-ports' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "active": true,
    "custom_reference": "OPS-ROTTERDAM-114",
    "name": "Rotterdam port call watch",
    "description": "Entry and exit alerts for the Rotterdam port area",
    "settings": {
        "email_settings": {
            "email_enabled": true,
            "scheduler": {
                "schedule_type": 1,
                "at_time": "12:00"
            }
        },
        "notification_callback_url": "https://webhooks.example.com/event-notifications",
        "filters": {
            "flag_codes": {
                "incl": [
                    "ZMB",
                    "MUS"
                ]
            },
            "event_types": [
                "ZONE_ENTRY",
                "ZONE_EXIT",
                "PORT_ARRIVAL",
                "PORT_DEPARTURE"
            ],
            "vessels": [
                "9074729"
            ],
            "zones_ports": [
                "5e98acb5-4b8a-451b-9280-ddd63d55f8c9",
                "1c60546c-da9d-425c-8eed-0142af219601"
            ]
        }
    }
}'

Response Example

201 - created

{
    "active": true,
    "callback_url_status": "pending",
    "created_at": "2026-08-12T10:15:30Z",
    "created_by": "user@example.com",
    "custom_reference": "OPS-ROTTERDAM-114",
    "subscription_id": "1c60546c-da9d-425c-8eed-0142af219601",
    "last_modified_at": "2026-08-12T10:15:30Z",
    "description": "Entry and exit alerts for the Rotterdam port area",
    "name": "Rotterdam port call watch",
    "settings": {
        "notification_callback_url": "https://webhooks.example.com/event-notifications"
    }
}

Modified at 2026-10-21 13:57:11

Zone & Port Notifications: Worked Examples

Get Zone & Port Notification Subscriptions