Developer Portal
InsightsPurpleTRAC
MTIPodium
Other
Other
  • Weather
InsightsPurpleTRAC
MTIPodium
Other
Other
  • Weather
  1. Tracking
  • Start Here
    • Overview
    • Getting started
    • Authentication
    • Testing
    • Errors & status codes
    • FAQ
  • General
    • Retrieve a list of vessels
      GET
    • Additional entity search
      GET
  • Screening
    • Screening a vessel
    • Watchlist checks
    • Additional checks
    • Movement history
    • Carbon rating
    • Submit a vessel for screening
      POST
    • Retrieve a list of transactions and their screening results
      GET
    • Ship & Flag Watchlist check
      GET
    • Company Watchlist check
      GET
    • Country Sanctions check
      GET
    • Ship movement history
      GET
    • Ship-to-Ship (STS) pairing screening
      GET
    • Company history check
      GET
    • P&I Club check
      GET
    • Vessel operational status
      GET
    • Flag history check
      GET
    • AIS positional discrepancy (spoofing) events
      GET
    • Periods of Non-Reporting
      GET
    • Carbon rating details
      GET
    • Get the PurpleTRAC Screening Report PDF
      GET
    • Submit a vessel for rescreening
      PUT
    • Archive a Screening
      PUT
  • Tracking
    • Voyage updates
    • Notification catalogue
    • Additional entities
    • Tracking a vessel
    • Enable a vessel for tracking
      PUT
    • Remove additional entities from a tracked vessel
      DELETE
    • Add additional entities to a tracked vessel
      PUT
    • List the additional entities on a transaction
      GET
    • Update voyage and tracking details
      PUT
    • Get vessel positional data
      GET
    • Retrieve a list of vessel or bill of lading notifications
      GET
    • Get the PurpleTRAC Trade Report PDF
      GET
  • Bill of Lading
    • Carriers
    • Verification
    • Submit a Bill of Lading for screening
    • Get all BL Screening Results
    • Get a single BL screening result
    • Get the PurpleTRAC Bill of Lading Screening Report PDF
    • Enable tracking for a screened Bill of Lading
    • Get the PurpleTRAC Bill of Lading Tracking Report PDF
    • Disable tracking for a Bill of Lading
  • Containers
    • Screening
    • Carriers
    • Submit a Container for screening
    • Get all Container Screening Results
    • Archive Container
    • Get a single Container screening result
    • Get the Container report
  • Schemas
    • BLVGetAllResultsResponse
    • BLVScreeningResponse
    • BLVLastScreeningResult
    • BLVScreeningResultDetails
    • ContainerRegistrationBody
    • ContainerRegistrationResponse
    • ContainerGetAllResultsResponse
    • ContainerScreeningResponse
    • CarbonRatings
    • CarbonRating
    • CompanySanctions
    • CompanySanction
    • CountryChecks
    • CountryCheck
    • StsPairings
    • StsPairing
    • OtherAssociations
    • OtherAssociation
    • CompanyHistoryChecks
    • CompanyHistoryCheck
    • ShipStatuses
    • ShipStatus
    • FlagHistoryChecks
    • FlagHistoryCheck
    • PositionalDiscrepancies
    • PositionalDiscrepancy
    • DiscrepancyZone
    • DiscrepancyPort
    • NonReportingResponse
    • NonReporting
    • Notifications
    • Notification
    • BLVNotification
    • BLVPortFull
    • BLVPortFallback
    • PortCallHistory
    • PortCallHistoryItem
    • Positions
    • Position
    • PositionInfo
    • RegistrationResponse
    • ShipDetails
    • ShipSanctions
    • ShipSanction
    • VesselTrackingResponse
    • VesselTransactionsResponse
    • Transaction
    • TransactionPutBody
    • TransactionPutResponse
    • TransactionRescreenResponse
    • LastPosition
    • ScreeningNotification
    • ScreeningResult
    • UserDetails
    • UserProfile
    • Error
    • InvalidContainerNumberResponse
    • VesselRegistrationBody
    • VesselTrackingRequest
    • BLRegistrationBody
    • AdditionalEntitySearchResponse
    • AdditionalEntity
    • AdditionalEntitiesRequestSchema
    • TrackingAdditionalEntity
    • TrackingAdditionalEntitiesResponse
    • TrackingAdditionalEntityInput
    • TrackingAdditionalEntitiesPutBody
    • TrackingAdditionalEntitiesPutResponse
    • TrackingAdditionalEntitiesDeleteBody
    • RemovedAdditionalEntity
    • TrackingAdditionalEntitiesDeleteResponse
    • TrackingAdditionalEntityError
    • FeatureDisabledError
    • ObjectNotFoundError
    • TransactionValidationError
    • VoyageUpdateRequest
    • VoyageUpdateResponse
    • PTracMeta
    • PTracVessel
    • PTracVesselSearchResponse
    • DuplicateTransactionError
  1. Tracking

Tracking Notifications

Every event raised against a tracked vessel arrives through GET /notification, with the event name in the event field. The tables below list all of them, grouped by what they report on.
Your account settings decide which of these are raised and what severity each one carries, so a track will not produce the full set. Your account admin edits those settings in the PurpleTRAC UI. Tracking a Vessel shows how to read the notification feed.

Positions and movement#

NotificationEvent nameTrigger
Position ReportPOSITION_REPORTShip sends position reports, AIS or Inmarsat C
Ship has Entered a PortPOSITION_PORT_ENTRYShip enters a port polygon
Ship has Exited a PortPOSITION_PORT_EXITShip exits a port polygon
Ship has Entered a High Risk Port AreaPOSITION_BLACKLIST_PORT_ENTRYShip enters a port polygon that has been blacklisted for the account
Ship is StationarySHIP_STOPPEDSpeed is 0.5 knots or less for two or more consecutive positions, and the ship is outside any port polygon
Ship is UnderwaySHIP_UNDERWAYShip sends a position report indicating it is moving again
Change of DraughtDRAUGHT_CHANGEDraught is read from the AIS position, and any change in draught raises this event
Dark activity/STS riskSTS_RISKA draught change was recorded after a period of non-reporting
Dark activity/STS risk in zoneSTS_RISK_IN_ZONEA draught change was recorded after a period of non-reporting in a zone

Reporting and tracking gaps#

NotificationEvent nameTrigger
AIS is Not ReportingAIS_SHIP_NOT_REPORTINGShip has stopped sending AIS position reports for more than 6 hours and is outside any port polygon
AIS is ReportingAIS_SHIP_REPORTINGShip sends an AIS position report indicating its AIS is reporting again
Ship Not TrackingSHIP_NOT_TRACKINGShip has sent no position report, AIS or Inmarsat C, for 24 hours or for the custom threshold set on the account
Ship TrackingSHIP_TRACKINGShip sends position reports, AIS or Inmarsat C, indicating it is tracking again

Voyage plan#

These fire against the ports and dates you set when enabling tracking, or amended later through Updating Voyage Details.
NotificationEvent nameTrigger
Ship DepartedSHIP_DEPARTEDShip has exited the departure port you set
Approach to Interim PortPORT_OF_CALL_APPROACHShip is within 30 nautical miles of an interim port you set
Arrival at Interim PortPORT_OF_CALL_ARRIVALShip has entered an interim port you set
Departure from Interim PortPORT_OF_CALL_DEPARTShip has departed an interim port you set
Approach to Destination - On ScheduleDESTINATION_APPROACH_ON_TIMEShip is within 30 nautical miles of the destination port you set, within 24 hours of the arrival date and time you set
Approach to Destination - LateDESTINATION_APPROACH_LATEShip is within 30 nautical miles of the destination port you set, more than 24 hours after the arrival date and time you set
Arrival at DestinationDESTINATION_ARRIVALShip has entered the destination port you set
Ship Off ScheduleDESTINATION_APPROACH_OFF_TRACKA position report lands within 24 hours of the arrival time you set, the ship is more than the configured distance from the destination port, and the ETA computed from its speed is more than 24 hours later than that arrival time

Zones#

NotificationEvent nameTrigger
Ship has entered a zoneZONE_ENTRYShip enters an industry or user defined zone, or is already inside it when tracking starts
Ship has exited a zoneZONE_EXITShip exits an industry or user defined zone
Ship in Proximity of Sanction ZoneBUFFER_ZONE_ENTRYShip enters a sanction buffer zone, within 120 nautical miles of a sanction zone
Ship Clear of Sanction ZoneBUFFER_ZONE_EXITShip exits a sanction buffer zone, moving beyond 120 nautical miles of a sanction zone
Ship Entered Sanction ZoneSANCTION_ZONE_ENTRYShip enters a sanction zone
Ship Exited Sanction ZoneSANCTION_ZONE_EXITShip exits a sanction zone
Ship Over 48 hours in Sanction ZoneSHIP_LONG_STAY_IN_SANCTION_ZONEShip has spent more than 48 hours in a sanction zone
Ship Entered War Risk ZoneWAR_ZONE_ENTRYShip enters a war risk zone
Ship Exited War Risk ZoneWAR_ZONE_EXITShip exits a war risk zone
Ship inside War Risk Zone with a MaRisk AlertSHIP_IN_WAR_ZONE_MARISK_ALERTShip enters a war zone where a MaRisk alert has occurred in the past 2 weeks

Watchlists, flag and ownership#

NotificationEvent nameTrigger
Ship on watchlistGLOBAL_SANCTION_LISTShip is added to a current global sanction list
Associated Company on Global Sanction ListCOMPANY_SANCTION_ADDEDAn associated company is added to a current watchlist
Ship changed to a sanctioned FlagSHIP_FLAG_SANCTIONEDShip's flag changes to a watchlist country
Ship Flag no longer sanctionedSHIP_FLAG_UNSANCTIONEDShip's flag is no longer a watchlist country
Registered Owner alertREGISTERED_OWNER_SANCTIONEDCountry of registration, domicile or control changed to a watchlist country, or became unknown
Registered Owner updateREGISTERED_OWNER_UNSANCTIONEDCountry of registration, domicile or control is no longer a watchlist country
Group Beneficial Owner alertGROUP_BENEFICIAL_OWNER_SANCTIONEDCountry of registration, domicile or control changed to a watchlist country, or became unknown
Group Beneficial Owner updateGROUP_BENEFICIAL_OWNER_UNSANCTIONEDCountry of registration, domicile or control is no longer a watchlist country
Operator alertOPERATOR_SANCTIONEDCountry of registration, domicile or control changed to a watchlist country, or became unknown
Operator updateOPERATOR_UNSANCTIONEDCountry of registration, domicile or control is no longer a watchlist country
Technical Manager alertTECHNICAL_MANAGER_SANCTIONEDCountry of registration, domicile or control changed to a watchlist country, or became unknown
Technical Manager updateTECHNICAL_MANAGER_UNSANCTIONEDCountry of registration, domicile or control is no longer a watchlist country
Ship Manager now in a Sanctioned CountrySHIP_MANAGER_SANCTIONEDShip's ship manager now belongs to a sanctioned country
Ship Manager no longer in a Sanctioned CountrySHIP_MANAGER_UNSANCTIONEDShip's ship manager no longer belongs to a sanctioned country

Screening and tracking lifecycle#

NotificationEvent nameTrigger
Screening CompleteSCREENING_COMPLETEScreening is completed
BLV screening reportBLV_SCREENING_COMPLETEBill of Lading verification screening is completed
Ship Selected for TrackingREADY_TO_TRACK_SHIPA user selects the ship for tracking
Ship DeregisteredSHIP_DEREGISTEREDShip tracking has completed, or was stopped by a user
Ship ArchivedSTATUS_DECLINEDShip screening has been moved to archive
Additional Entity AddedADDITIONAL_ENTITY_ADDEDOne or more additional entities were added to a tracked vessel through the additional entity PUT method. Requires the Additional Entity Ship Tracking feature
Additional Entity RemovedADDITIONAL_ENTITY_REMOVEDOne or more additional entities were removed from a tracked vessel through the additional entity DELETE method. Requires the Additional Entity Ship Tracking feature
Management ReportMANAGEMENT_REPORTThe management report is emailed automatically, at the frequency set for the user

Related#

Tracking a Vessel
Enable a track, then read positions and notifications.
Managing Additional Entities
The workflow behind the two additional entity notifications.
Updating Voyage Details
Set the ports and dates the voyage plan notifications fire against.
Modified at 2026-10-02 12:27:10
Previous
Voyage updates
Next
Additional entities
Built with