Screen a vessel with the PurpleTRAC API

Screening is the call that starts everything else in PurpleTRAC. POST /registration returns a transaction id, and that id is what every later call takes: the results, the detailed checks, the PDF report, rescreening, tracking.

Screening runs asynchronously. Registration returns straight away with an id, and you read the outcome from GET /transaction once the screening has finished. The only calls you can make before registering a vessel are the vessel search and, if you use additional entities, the entity search.

Find the vessel

Skip this if you already hold the IMO number. Otherwise GET /sisship searches the Pole Star vessel database on a full or partial name and returns enough detail to confirm you have the right ship.

The objects array can come back empty, with one vessel, or with several.

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "flag_alpha_2": "BD",
            "flag_code": "BGD",
            "image": "http://net.polestarglobal.sis-photos.s3.amazonaws.com/1355274_2.jpg",
            "imo_number": "9221126",
            "mmsi": "405000251",
            "ship_name": "STAR ROYAL",
            "ship_status": "In Service/Commission",
            "ship_type": "Bulk Carrier"
        }
    ]
}

Swap ship_name__istartswith for imo_number__startswith to search on a full or partial IMO number. That is also how you confirm an IMO exists in the database before you screen it.

Submit the vessel for screening

POST /registration takes the IMO number in registered_name. carbon_rating and client_reference are both optional, defaulting to false and null.

{
    "added_via": "MANUAL",
    "carbon_rating": false,
    "client_reference": "Custom reference field",
    "registered_name": "9221126",
    "resource_uri": "/api/v1/registration/None",
    "transaction_id": 2840116
}

Store transaction_id. Every step below needs it.

Read the screening result

GET /transaction returns both the status and the results, so poll the same call until the screening finishes. While it is running, screening_status holds "PENDING". When it finishes, the field holds the overall result: "OK", "WARNING" or "CRITICAL".

How long a screening takes

Most screenings complete in 5 to 10 seconds. A few take up to 2 minutes, so poll the status instead of assuming a fixed wait.

The response carries the transaction, the vessel, the last known position, the notifications raised so far, and the result of each compliance check.

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "additional_entities": [],
            "ais_gap_status": "F",
            "arrival_date": null,
            "auto_deregister": true,
            "blv": null,
            "blv_id": null,
            "client_reference": "",
            "closed_date": null,
            "container_screen_id": null,
            "creation_date": "2023-11-29T16:03:56Z",
            "departure_date": null,
            "departure_port": null,
            "destination_port": null,
            "has_gaps": true,
            "id": 2840116,
            "interim_ports": [],
            "last_position": {
                "creation_date": "2023-11-29 16:25:08.631431+00:00",
                "destination": "SGP",
                "destination_eta": "2023-12-01 09:00:00+00:00",
                "draught": 12.3,
                "heading": 311,
                "id": 648089806,
                "latitude": "-1.560678",
                "longitude": "108.083565",
                "position_type": "AIS",
                "speed": "9.10",
                "status": null,
                "status_timestamp": "2023-11-29 15:55:32+00:00",
                "timestamp": "2023-11-29 15:55:32+00:00"
            },
            "notifications": [
                {
                    "acknowledged": false,
                    "comment": "",
                    "creation_date": "2023-11-29T16:25:20Z",
                    "event": "SCREENING_COMPLETE",
                    "event_date": "2023-11-29T16:25:20Z",
                    "id": 52235728,
                    "last_updated_date": "2023-11-29T16:25:20Z",
                    "related_text": "",
                    "resource_uri": "/api/v1/notification/52235728",
                    "severity": "WARNING",
                    "updated_since_creation": false
                },
                {
                    "acknowledged": false,
                    "comment": "",
                    "creation_date": "2023-11-29T16:04:14Z",
                    "event": "SCREENING_COMPLETE",
                    "event_date": "2023-11-29T16:04:14Z",
                    "id": 52235078,
                    "last_updated_date": "2023-11-29T16:04:14Z",
                    "related_text": "",
                    "resource_uri": "/api/v1/notification/52235078",
                    "severity": "WARNING",
                    "updated_since_creation": false
                }
            ],
            "num_notes": 0,
            "num_notifications": 2,
            "overall_severity": "WARNING",
            "registered_date": null,
            "registered_name": "9221126",
            "report_generation_complete": true,
            "resource_uri": "/api/v1/transaction/2840116",
            "screen_results": [
                {
                    "check": "CARBON_RATING",
                    "creation_date": "2023-11-29T16:24:58Z",
                    "id": 14778178,
                    "resource_uri": "/api/v1/screenresult/14778178",
                    "result_code": null,
                    "status": "OK"
                },
                {
                    "check": "COMPANY_SANCTIONS",
                    "creation_date": "2023-11-29T16:24:58Z",
                    "id": 14778177,
                    "resource_uri": "/api/v1/screenresult/14778177",
                    "result_code": null,
                    "status": "OK"
                },
                {
                    "check": "PSC_HISTORY",
                    "creation_date": "2023-11-29T16:24:58Z",
                    "id": 14778175,
                    "resource_uri": "/api/v1/screenresult/14778175",
                    "result_code": null,
                    "status": "OK"
                },
                {
                    "check": "SANCTIONS",
                    "creation_date": "2023-11-29T16:24:58Z",
                    "id": 14778176,
                    "resource_uri": "/api/v1/screenresult/14778176",
                    "result_code": null,
                    "status": "OK"
                },
                {
                    "check": "SHIP_MOVE_HIST",
                    "creation_date": "2023-11-29T16:24:58Z",
                    "id": 14778174,
                    "resource_uri": "/api/v1/screenresult/14778174",
                    "result_code": null,
                    "status": "WARNING"
                }
            ],
            "screening_expired": false,
            "screening_status": "WARNING",
            "ship": {
                "age": 22,
                "build_year": 2001,
                "call_sign": "S2AR2",
                "flag": {
                    "code": "BGD",
                    "iso_3166_1_alpha_2": "BD",
                    "name": "Bangladesh"
                },
                "id": 272962,
                "image": "/ship-image/430441_2.jpg",
                "imo_number": "9221126",
                "length": 189,
                "mmsi": "405000251",
                "operator": "Vanguard Maritime Ltd",
                "registered_owner": "Vanguard Maritime Ltd",
                "resource_uri": "/api/v1/ship/272962",
                "ship_name": "STAR ROYAL",
                "ship_type": "Bulk Carrier",
                "ship_status": "In Service/Commission",
                "status": "A",
                "weight": 29499
            },
            "status": "H",
            "tracking_expiry": null,
            "transceiver_domain": "",
            "transceiver_domain_id": "",
            "user": {
                "email": "api.user@example.com",
                "first_name": "API",
                "id": 6913,
                "last_name": "Access",
                "resource_uri": "/api/v1/user/6913",
                "userprofile": {
                    "company_logo": null,
                    "help_index": "/help/Lender/Default.htm",
                    "language": null,
                    "mng_report_frequency": "NEVER",
                    "mobile_phone_number": "",
                    "office_phone_extension": "",
                    "office_phone_number": "",
                    "resource_uri": "/api/v1/userprofile/6905",
                    "role": "PU"
                }
            }
        }
    ]
}

overall_severity aggregates the underlying compliance checks into one value. In this response it is "WARNING", driven by the SHIP_MOVE_HIST check.

The ids the detailed checks need

Each entry in screen_results carries its own id, and the detailed check endpoints take that id instead of the transaction id. Read them from this response before you call anything below.

`check` value	Detailed results
`SANCTIONS`	Ship and flag watchlist hits, Detailed Watchlist Checks
`COMPANY_SANCTIONS`	Company and country watchlist hits, Detailed Watchlist Checks
`SHIP_MOVE_HIST`	Port calls, Vessel Movement History
`CARBON_RATING`	Carbon rating metrics, Vessel Carbon Rating
`PSC_HISTORY`	Port state control history

Download the screening report

Once the screening has finished, GET /screening_report returns the PurpleTRAC PDF for the transaction.

A report that has not finished generating returns 500 with an empty body. Wait and call again.

Rescreen a vessel

PUT /transaction/{id}/rescreen refreshes the results and keeps the transaction id, so anything you have stored against that id stays valid.

Rescreening stops tracking

A vessel that is currently tracking stops tracking when you rescreen it. Use rescreening on vessels you are not tracking.

{
    "added_via": "MANUAL",
    "ais_gap_status": "F",
    "ais_received": null,
    "ais_reporting": true,
    "auto_deregister": true,
    "auto_deregistered": false,
    "auto_register": true,
    "blv": null,
    "carbon_rating_screen": true,
    "client_reference": "",
    "closed_date": null,
    "container_screen_id": null,
    "creation_date": "2023-11-29T16:03:56.133881",
    "has_gaps": true,
    "id": 2840116,
    "inmarsatc_expected": null,
    "inmarsatc_interval": 2,
    "inmarsatc_received": null,
    "inmarsatc_reporting": true,
    "only_tracking_by_ais": false,
    "overall_severity": "WARNING",
    "registered_date": null,
    "registered_name": "9221126",
    "report_generation_complete": true,
    "resource_uri": "/api/v1/transaction/2840116",
    "screened_date": "2023-11-29T16:25:11.276888",
    "screening_status": "WARNING",
    "ship": "/api/v1/shipdetails/272962",
    "status": "H",
    "tracking_date": null,
    "tracking_expiry": null,
    "transceiver_domain": "",
    "transceiver_domain_id": "",
    "user": "/api/v1/user/6913",
    "voyage": null
}

Get the report for a rescreening

A rescreening produces a new version of the PDF, identified by a document_id. The only place that id appears is the notification feed, on the latest SCREENING_COMPLETE event for the transaction.

{
    "acknowledged": false,
    "blv": null,
    "cleared": false,
    "comment": "",
    "creation_date": "2025-09-02T15:10:28.777392+00:00",
    "document_id": 8725514,
    "event": "SCREENING_COMPLETE",
    "event_date": "2025-09-02T15:10:28.773121+00:00",
    "id": 82818816,
    "last_updated_date": "2025-09-02T15:10:28.777416+00:00",
    "parent_notification_id": null,
    "related_obj_id": null,
    "related_text": "",
    "resource_uri": "/api/v1/notification/82818816",
    "severity": "WARNING",
    "transaction": "/api/v1/transaction/4815309",
    "updated_since_creation": false,
    "user": "/api/v1/user/6913"
}

Pass both ids to the report endpoint. Without document_id you get the original screening report, not the rescreening.

Archive a vessel

Archiving, also called deregistering, separates finished work from active work. Nothing is deleted, and the transaction stays readable.

Send PUT /transaction/{id} with the transaction id and "status": "C" in the body.

Archiving stops tracking

A tracked vessel that you archive stops tracking.

The response returns the transaction with status set to "C".

{
  "added_via": "MANUAL",
  "ais_gap_status": "F",
  "ais_received": null,
  "ais_reporting": true,
  "auto_deregister": true,
  "auto_deregistered": false,
  "auto_register": true,
  "blv": null,
  "carbon_rating_screen": false,
  "client_reference": "my custom reference",
  "closed_date": null,
  "container_screen_id": null,
  "creation_date": "2023-12-05T13:24:46.500470",
  "has_gaps": true,
  "id": 2849764,
  "inmarsatc_expected": null,
  "inmarsatc_interval": 2,
  "inmarsatc_received": null,
  "inmarsatc_reporting": true,
  "only_tracking_by_ais": false,
  "overall_severity": "WARNING",
  "registered_date": null,
  "registered_name": "9221126",
  "report_generation_complete": true,
  "resource_uri": "/api/v1/transaction/2849764",
  "screened_date": "2023-12-05T13:39:33.980235",
  "screening_status": "WARNING",
  "ship": "/api/v1/shipdetails/272962",
  "status": "C",
  "tracking_date": null,
  "tracking_expiry": null,
  "transceiver_domain": "",
  "transceiver_domain_id": "",
  "user": "/api/v1/user/6913",
  "voyage": null
}

List every screening on the account

Drop the id parameter and GET /transaction returns every screening on the account, in the same shape as a single read.

Page through the results with offset, or follow the next and previous links in the meta object. The same endpoint also filters on status__in, ship__imo_number and client_reference, and sorts on order_by.

The client reference field

client_reference is a free text value you set on POST /registration and read back on every GET /transaction. Put your own vessel identifier or case number in it and you can match a PurpleTRAC transaction to your own records without keeping a separate mapping table.

Screen additional entities

Additional entities are companies or people you want screened alongside the vessel. Watchlist hits against them appear in the screening report and in the company watchlist check response.

Additional entity screening is an addon

Contact your Pole Star representative to have it enabled on your account.

Include them in the POST /registration body:

{
  "registered_name": "9231808",
  "additional_entities": [
    {
      "name": "Spacelabs Medical",
      "relationship": "",
      "type": "organisation",
      "obj_id": "882110"
    },
    {
      "name": "Space Radio Telecommunications Equipment",
      "relationship": "",
      "type": "organisation",
      "obj_id": "3448328"
    }
  ]
}

name is mandatory and has to be an exact match of the organisation or person you want screened.

relationship has to be present and may be null. It is free text describing how the entity relates to the vessel.

type acts as a filter, either organisation or person. Set it to exclude the other type from the matching.

obj_id is the unique identifier returned by the entity search below. Supplying it pins the screening to the entity you meant.

obj_id is optional, and an entity that the search returns nothing for can still be screened. The name has to match exactly in that case.

Search for an entity first

We recommend searching for the entity by name before you screen it, with GET /additional_entity_search. Matched entities come back with an obj_id you can pass in the registration body.

The search doubles as a watchlist check. An entity the search does not return has no watchlists associated with it.

Four entities match "Tesla":

"objects": [
    {
        "address_city": "Zagreb;;10000",
        "address_country": "CRTIA",
        "address_line": "Trnjanska cesta 5",
        "citizenship": null,
        "date_of_birth": null,
        "name": "Tesla Energenti",
        "obj_id": 11944745,
        "resident_of": null,
        "type": "organisation"
    },
    {
        "address_city": "Zagreb;;10000",
        "address_country": "CRTIA",
        "address_line": "Trnjanska cesta 5",
        "citizenship": null,
        "date_of_birth": null,
        "name": "Tesla Energenti za usluge i trgovinu",
        "obj_id": 11944745,
        "resident_of": null,
        "type": "organisation"
    },
    {
        "address_city": "Tehran",
        "address_country": "IRAN",
        "address_line": "No.15, Ground Floor, Abbasian Passage, After Hafez Bridge, Jomhouri St.",
        "citizenship": null,
        "date_of_birth": null,
        "name": "Tesla Hooshmand Sazan",
        "obj_id": 13388164,
        "resident_of": null,
        "type": "organisation"
    },
    {
        "address_city": "Tehran",
        "address_country": "IRAN",
        "address_line": "No.15, Ground Floor, Abbasian Passage, After Hafez Bridge, Jomhouri St.",
        "citizenship": null,
        "date_of_birth": null,
        "name": "Tesla Hooshmand Sazan Company",
        "obj_id": 13388164,
        "resident_of": null,
        "type": "organisation"
    }
]

Four companies whose names start with "Tesla" appear on one or more watchlists. Tesla Inc. does not.

The name search uses starts-with logic, so a search term has to include the first characters of the name.

Exclude matches you do not want

An entity name can pull in matches you have no interest in. Pass those matches back in a not array inside the entity object and the screening ignores them.

Searching for "DSM" returns five entities:

"objects": [
    {
        "address_city": "Geoje;Gyeongsangnam-Do;53302",
        "address_country": "SKOREA",
        "address_line": "3370, Geoje-Daero",
        "citizenship": null,
        "date_of_birth": null,
        "name": "DSME",
        "obj_id": 1048985,
        "resident_of": null,
        "type": "organisation"
    },
    {
        "address_city": "Geoje;Gyeongsangnam-Do;53302",
        "address_country": "SKOREA",
        "address_line": "3370, Geoje-Daero",
        "citizenship": null,
        "date_of_birth": null,
        "name": "DSME E and R",
        "obj_id": 1048985,
        "resident_of": null,
        "type": "organisation"
    },
    {
        "address_city": "Geoje;Gyeongsangnam-Do;53302",
        "address_country": "SKOREA",
        "address_line": "3370, Geoje-Daero",
        "citizenship": null,
        "date_of_birth": null,
        "name": "DSME E&R",
        "obj_id": 1048985,
        "resident_of": null,
        "type": "organisation"
    },
    {
        "address_city": null,
        "address_country": null,
        "address_line": null,
        "citizenship": "BYELRS",
        "date_of_birth": "1970-07-07",
        "name": "Dsmitry Aljaksandrawitsch Schuk",
        "obj_id": 713200,
        "resident_of": "BYELRS",
        "type": "person"
    },
    {
        "address_city": null,
        "address_country": null,
        "address_line": null,
        "citizenship": "BYELRS",
        "date_of_birth": null,
        "name": "Dsmitryj Pjatrowitsch Aljaksandrau",
        "obj_id": 1503904,
        "resident_of": "BYELRS",
        "type": "person"
    }
]

To screen the organisation called "DSM" without any of them:

{
  "registered_name": "9231808",
  "additional_entities": [
    {
      "name": "DSM",
      "relationship": "",
      "type": "organisation",
      "not": [
        {
            "address_city": "Geoje;Gyeongsangnam-Do;53302",
            "address_country": "SKOREA",
            "address_line": "3370, Geoje-Daero",
            "citizenship": null,
            "date_of_birth": null,
            "name": "DSME",
            "obj_id": 1048985,
            "resident_of": null,
            "type": "organisation"
        },
        {
            "address_city": "Geoje;Gyeongsangnam-Do;53302",
            "address_country": "SKOREA",
            "address_line": "3370, Geoje-Daero",
            "citizenship": null,
            "date_of_birth": null,
            "name": "DSME E and R",
            "obj_id": 1048985,
            "resident_of": null,
            "type": "organisation"
        },
        {
            "address_city": "Geoje;Gyeongsangnam-Do;53302",
            "address_country": "SKOREA",
            "address_line": "3370, Geoje-Daero",
            "citizenship": null,
            "date_of_birth": null,
            "name": "DSME E&R",
            "obj_id": 1048985,
            "resident_of": null,
            "type": "organisation"
        },
        {
            "address_city": null,
            "address_country": null,
            "address_line": null,
            "citizenship": "BYELRS",
            "date_of_birth": "1970-07-07",
            "name": "Dsmitry Aljaksandrawitsch Schuk",
            "obj_id": 713200,
            "resident_of": "BYELRS",
            "type": "person"
        },
        {
            "address_city": null,
            "address_country": null,
            "address_line": null,
            "citizenship": "BYELRS",
            "date_of_birth": null,
            "name": "Dsmitryj Pjatrowitsch Aljaksandrau",
            "obj_id": 1503904,
            "resident_of": "BYELRS",
            "type": "person"
        }
      ]
    }
  ]
}

This request carries no obj_id for DSM, because the company being screened does not appear in the search results.

Read the additional entity results

Hits against additional entities reach you in two places: the Company Watchlist Alerts section of the PDF screening report, and the objects array of GET /companysanction.

{
    "additional_entity_relationship": "Owner",
    "associate_compliance_id": null,
    "associate_name": null,
    "associate_relationship": null,
    "associate_type": null,
    "company_code": null,
    "company_name": "Commercial Vehicles - GAZ Group",
    "compliance_company_name": "Commercial Vehicles - GAZ Group",
    "compliance_id": 179795,
    "id": 13829044,
    "ignored": false,
    "resource_uri": "/api/v1/companysanction/13829044",
    "sanction_name": "EC 2023/429 Ukraine List",
    "screenresult": "/api/v1/screenresult/20905926",
    "severity": "CRITICAL",
    "ship_relationship": "ADDITIONAL_ENTITY",
    "since_date": "2023-02-25",
    "to_date": null
}

ship_relationship always reads ADDITIONAL_ENTITY on these records. additional_entity_relationship echoes the relationship value you supplied at screening.

Change entities after screening

Entities are not fixed at the point of screening. Once a vessel is selected for tracking, you can list, add and remove entities on the transaction without rescreening the vessel:

GET /transaction/{id}/additional_entity lists what is currently tracked on the transaction.

PUT /transaction/{id}/additional_entity adds entities, and reruns the company watchlist check.

DELETE /transaction/{id}/additional_entity removes entities from further screening.

Managing Additional Entities has the full workflow, including the tracking status requirement and the cap of ten entities added during tracking.

Watchlist Checks

Ship, flag, company and country hits behind a SANCTIONS or COMPANY_SANCTIONS result.

Additional Checks

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

Vessel Tracking

Turning a screened transaction into live positions and notifications.

Screening a Vessel

Find the vessel#

Submit the vessel for screening#

Read the screening result#

The ids the detailed checks need#

Download the screening report#

Rescreen a vessel#

Get the report for a rescreening#

Archive a vessel#

List every screening on the account#

The client reference field#

Screen additional entities#

Search for an entity first#

Exclude matches you do not want#

Read the additional entity results#

Change entities after screening#

Related#

Find the vessel

Submit the vessel for screening

Read the screening result

The ids the detailed checks need

Download the screening report

Rescreen a vessel

Get the report for a rescreening

Archive a vessel

List every screening on the account

The client reference field

Screen additional entities

Search for an entity first

Exclude matches you do not want

Read the additional entity results

Change entities after screening

Related