Create Vessel Notification Subscription

Production

https://api.polestar-production.com

POST

/notifications/v1/vessels

Subscribe to events for one or more vessels, so movements reach you as
they happen rather than through polling.

settings.filters is keyed by event family. The ports filter takes
event_types (such as PORT_AREA_ARRIVAL or PORT_ARRIVAL) and can be
narrowed with port_ids, unlocodes, port_sub_types (such as
Port or Anchorage Area) and country_codes (ISO 3166-1 alpha-3, such
as VEN).

Request

Authorization

API Key

Add parameter in header

api-key

Example:

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

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

Vessel notification subscription created. Returns the new vessel 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/vessels' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "active": true,
    "custom_reference": "FLEET-OPS-2141",
    "description": "Zone entry and exit alerts for vessels transiting the Panama Canal",
    "name": "Panama Canal transit watch",
    "settings": {
        "email_settings": {
            "email_enabled": true,
            "scheduler": {
                "schedule_type": 24,
                "at_time": "10:10"
            }
        },
        "notification_callback_url": "https://webhooks.example.com/event-notifications",
        "imo": "9074729",
        "filters": {
            "zones": {
                "type": "zones",
                "active": true,
                "event_types": [
                    "ZONE_ENTRY",
                    "ZONE_EXIT"
                ],
                "zone_ids": [
                    "5e98acb5-4b8a-451b-9280-ddd63d55f8c9"
                ],
                "zone_types": [
                    "Jurisdictional"
                ],
                "zone_sub_types": [
                    "Internal Waters"
                ]
            },
            "ais_eta_change": {
                "type": "ais_eta_change",
                "active": true
            }
        }
    }
}'

Response Example

201 - created

{
    "active": true,
    "callback_url_status": "pending",
    "created_at": "2026-08-12T10:15:30Z",
    "created_by": "user@example.com",
    "custom_reference": "FLEET-OPS-2141",
    "subscription_id": "5e98acb5-4b8a-451b-9280-ddd63d55f8c9",
    "last_modified_at": "2026-08-12T10:15:30Z",
    "description": "Zone entry and exit alerts for vessels transiting the Panama Canal",
    "name": "Panama Canal transit watch",
    "settings": {
        "notification_callback_url": "https://webhooks.example.com/event-notifications",
        "imo": "9074729",
        "email_settings": {
            "email_enabled": true,
            "scheduler": {
                "schedule_type": 24,
                "at_time": "10:10"
            }
        }
    }
}

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

Get Vessel Notification Subscriptions

Get Vessel Notification Subscription