Getting started with the PurpleTRAC API

PurpleTRAC screens vessels, bills of lading and containers, and then tracks whichever of them you choose to keep watching. This page covers the shape shared by all three workflows, so the worked examples make sense when you reach them.

Before you start, read the Terms & Conditions for PurpleTRAC API use, and make sure you have your credentials.

Find the vessel first

Screening takes an identifier, so most integrations begin with a search. GET /sisship accepts filters on name and IMO number, and returns the vessels that match.

The transaction id

Screening something for the first time creates a transaction id. Almost every call after that needs it: fetching results, enabling tracking, rescreening, downloading a report.

Submit a vessel with POST /registration:

{
    "added_via": "MANUAL",
    "carbon_rating": true,
    "client_reference": null,
    "registered_name": "9221126",
    "resource_uri": "/api/v1/registration/2840116",
    "transaction_id": 2840116
}

Store transaction_id. It is the handle for everything that follows.

Some checks need a second id rather than the transaction id. Those ids come back inside the screening results, and each worked example shows where to find the one it needs.

Screening a vessel

Once the screening completes, the results are spread across endpoints so you fetch only what you need.

You want	Call
The high level result, and the ids the detailed checks need	`GET /transaction`
Ship and flag watchlist checks	`GET /shipsanction`
Company watchlist checks	`GET /companysanction`
Country sanctions checks	`GET /countrycheck`
Port calls, meaning ship movement history	`GET /porthistory`
Periods of non-reporting	`GET /non-reporting`
Carbon rating	`GET /carbonrating`
The PDF screening report	`GET /screening_report`

Start at GET /transaction. Its response carries the object ids that the detailed check endpoints expect, so calling it first saves you guessing.

To refresh a vessel later, submit it for rescreening with PUT /transaction/{id}/rescreen rather than registering it again. Rescreening keeps the original transaction id, so your stored handle stays valid and the history stays in one place.

Archiving a screened vessel with PUT /transaction/{id} is optional. It keeps current work separate from finished work, which makes filtering by status easier later.

Tracking a vessel

Tracking follows screening. A vessel has to be screened before it can be tracked, and you enable tracking with the transaction id from that screening.

Enable tracking

PUT /transaction/{id}/track. The transaction moves to Ready to Track, "status": "R".

Wait for approval

Once approved the status becomes "status": "A", and positions and notifications start being generated.

Read positions and events

GET /position for positional data, GET /notification for events. Both take the transaction id.

Collect the trade report

When tracking stops, by your instruction or by the configuration set when you enabled it, a trade report covering the voyage becomes available at GET /trade_report.

You can also add entities to a tracked vessel, and update voyage details, while tracking runs. Managing Additional Entities and Updating Voyage Details cover those.

Screening a bill of lading

The same shape, with its own id. POST /blv returns a transaction id, GET /blv/{id} returns the results once screening completes, and GET /blv_report gives you the PDF.

Tracking works the same way too. PUT /blv/{id}/track enables it, and notifications come from GET /notification, the same endpoint as vessel notifications, using the bill of lading transaction id. Tracking stops automatically when the bill of lading reaches its destination, and GET /blv_tracking_report then returns the tracking report.

Check the carrier is supported

Bill of lading screening depends on the carrier. List of Bill of Lading Carriers has the current list.

Screening a container

POST /containers returns a container_screen_id. Use it with GET /containers/{id} to read results once screening completes, and GET /containers/{id}/report for the PDF.

Check the carrier is supported

Container screening depends on the carrier. List of Container Carriers has the current list.

What your account configuration controls

Pole Star configures your account at onboarding, and those settings change what your results say rather than which calls succeed.

Carbon Rating, BL Verification and Container Screening are addons, switched on per account

Compliance watchlist selection

Flag and company history lookback periods

Non-reporting gap threshold

Warning and critical severity bands on individual checks

Ship not tracking thresholds

Your Pole Star representative goes through these with you at account creation, and can amend them later. If an endpoint returns 403, the addon behind it is not enabled.

Worked examples

Screening Vessels

Watchlist Checks

Ship, company and country checks in detail.

Movement History

Port calls and where the two history sources differ.

Vessel Tracking

Enabling tracking, then reading positions and notifications.

Carbon Rating

Retrieving a vessel's carbon rating.

Additional Checks

STS pairing, positional discrepancy, flag and company history, P&I club and ship status.

Getting Started with PurpleTRAC

Find the vessel first#

The transaction id#

Screening a vessel#

Tracking a vessel#

Screening a bill of lading#

Screening a container#

What your account configuration controls#

Worked examples#

Find the vessel first

The transaction id

Screening a vessel

Tracking a vessel

Screening a bill of lading

Screening a container

What your account configuration controls

Worked examples