Watchlist checks in the PurpleTRAC API

GET /transaction gives you the headline screening result. The watchlist detail sits behind three further endpoints: GET /shipsanction for the ship and its flag, GET /companysanction for the companies around the vessel, and GET /countrycheck for the countries those companies are tied to.

All three work the same way. Take the id of the relevant check from the screen_results array on the transaction, then pass it as screenresult.

Wait for the screening to finish

These endpoints return results only once screening_status has moved from "PENDING" to OK, WARNING or CRITICAL. Screening a Vessel covers the polling.

Ship and flag watchlist check

This check tests the ship's IMO number and its associated flag against the watchlists configured on your account. A WARNING or CRITICAL result has one of three causes: the vessel is on a watchlist, its flag is a watchlist country, or both.

Find the id

In the screen_results array returned by GET /transaction, find the object whose check is SANCTIONS.

{
  "check": "SANCTIONS",
  "creation_date": "2023-12-05T14:14:34Z",
  "id": 14837195,
  "resource_uri": "/api/v1/screenresult/14837195",
  "result_code": null,
  "status": "CRITICAL"
}

Retrieve the results

Pass that id as the screenresult parameter.

Each object is one watchlist entry, with the period it applied for in since_date and to_date. A to_date of null means the listing is current.

{
    "meta": {
        "limit": 100,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 3
    },
    "objects": [
        {
            "compliance_id": 3458,
            "entity_name": "FELICITY",
            "entity_type": "ship",
            "id": 291026,
            "ignored": false,
            "resource_uri": "/api/v1/shipsanction/291026",
            "sanction_name": "OFAC - Specially Designated National List",
            "screenresult": "/api/v1/screenresult/14837195",
            "severity": "CRITICAL",
            "since_date": "2013-03-14",
            "to_date": "2016-01-16"
        },
        {
            "compliance_id": 3458,
            "entity_name": "FELICITY",
            "entity_type": "ship",
            "id": 291026,
            "ignored": false,
            "resource_uri": "/api/v1/shipsanction/291026",
            "sanction_name": "OFAC - Executive Order 13599",
            "screenresult": "/api/v1/screenresult/14837195",
            "severity": "CRITICAL",
            "since_date": "2016-01-16",
            "to_date": "2018-11-05"
        },
        {
            "compliance_id": 3458,
            "entity_name": "FELICITY",
            "entity_type": "ship",
            "id": 291026,
            "ignored": false,
            "resource_uri": "/api/v1/shipsanction/291026",
            "sanction_name": "OFAC - Specially Designated National List",
            "screenresult": "/api/v1/screenresult/14837195",
            "severity": "CRITICAL",
            "since_date": "2018-11-05",
            "to_date": null
        }
    ]
}

objects comes back empty when the ship, the flag and the associated entities are all clear.

Company and country watchlist check

This check screens the ownership and management entities against regulatory watchlists, and screens their countries of registration, domicile and control against country watchlists. A WARNING or CRITICAL result again has three causes: a company is listed, a country of registration, domicile or control is a watchlist country, or both.

Both halves share one id and split across two endpoints.

Find the id

This time look for the object whose check is COMPANY_SANCTIONS.

{
  "check": "COMPANY_SANCTIONS",
  "creation_date": "2023-12-05T14:14:34Z",
  "id": 14837196,
  "resource_uri": "/api/v1/screenresult/14837196",
  "result_code": null,
  "status": "CRITICAL"
}

Company watchlist results

GET /companysanction returns the companies associated with the vessel that appear on a watchlist configured for your account.

ship_relationship names how the company connects to the vessel. Where the hit comes through an associate of that company instead, ship_relationship is null and the associate_* fields carry the link.

{
    "meta": {
        "limit": 10,
        "next": "/api/v1/companysanction?screenresult=14837196&api_key=&username=&limit=10&offset=10",
        "offset": 0,
        "previous": null,
        "total_count": 59
    },
    "objects": [
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": null,
            "associate_name": null,
            "associate_relationship": null,
            "associate_type": null,
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "National Iranian Tanker Company",
            "compliance_id": 138234,
            "id": 9678295,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9678295",
            "sanction_name": "EC 2015/1862 Iran List",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "OK",
            "ship_relationship": "SHIP_MANAGER",
            "since_date": "2015-10-18",
            "to_date": "2016-01-16"
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": null,
            "associate_name": null,
            "associate_relationship": null,
            "associate_type": null,
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "National Iranian Tanker Company",
            "compliance_id": 138235,
            "id": 9678296,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9678296",
            "sanction_name": "EC (CFSP) 2015/1863 Iran List",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "OK",
            "ship_relationship": "SHIP_MANAGER",
            "since_date": "2015-10-18",
            "to_date": "2016-01-16"
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": null,
            "associate_name": null,
            "associate_relationship": null,
            "associate_type": null,
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "National Iranian Tanker Company",
            "compliance_id": 139126,
            "id": 9678297,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9678297",
            "sanction_name": "OFAC - Specially Designated National List",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "OK",
            "ship_relationship": "SHIP_MANAGER",
            "since_date": "2012-07-12",
            "to_date": "2016-01-16"
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": null,
            "associate_name": null,
            "associate_relationship": null,
            "associate_type": null,
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "National Iranian Tanker Company",
            "compliance_id": 140432,
            "id": 9678298,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9678298",
            "sanction_name": "DFAT (Australia) Consolidated List",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "OK",
            "ship_relationship": "SHIP_MANAGER",
            "since_date": "2013-07-04",
            "to_date": "2016-01-18"
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": 1055238,
            "associate_name": "National Iranian Tanker Company",
            "associate_relationship": "Associate",
            "associate_type": "organisation",
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "N.I.T.C. Representative Office",
            "compliance_id": 150800,
            "id": 9677741,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9677741",
            "sanction_name": "Rhode Island Office of the General Treasurer – Scrutinized Companies List Iran",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL",
            "ship_relationship": null,
            "since_date": null,
            "to_date": null
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": 1055238,
            "associate_name": "National Iranian Tanker Company",
            "associate_relationship": "Associate",
            "associate_type": "organisation",
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "N.I.T.C. Representative Office",
            "compliance_id": 119398,
            "id": 9677742,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9677742",
            "sanction_name": "New York Iran Divestment Act of 2012",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL",
            "ship_relationship": null,
            "since_date": null,
            "to_date": null
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": 1055238,
            "associate_name": "National Iranian Tanker Company",
            "associate_relationship": "Associate",
            "associate_type": "organisation",
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "N.I.T.C. Representative Office",
            "compliance_id": 132650,
            "id": 9677743,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9677743",
            "sanction_name": "EC 945/2012 Iran List",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL",
            "ship_relationship": null,
            "since_date": "2012-10-15",
            "to_date": null
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": 1055238,
            "associate_name": "National Iranian Tanker Company",
            "associate_relationship": "Associate",
            "associate_type": "organisation",
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "N.I.T.C. Representative Office",
            "compliance_id": 132651,
            "id": 9677744,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9677744",
            "sanction_name": "EC 2012/635/CFSP Iran List",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL",
            "ship_relationship": null,
            "since_date": "2012-10-15",
            "to_date": null
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": 1055238,
            "associate_name": "National Iranian Tanker Company",
            "associate_relationship": "Associate",
            "associate_type": "organisation",
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "N.I.T.C. Representative Office",
            "compliance_id": 135631,
            "id": 9677745,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9677745",
            "sanction_name": "EC 2015/230 Iran List",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "OK",
            "ship_relationship": null,
            "since_date": "2015-02-12",
            "to_date": "2016-01-16"
        },
        {
            "additional_entity_relationship": null,
            "associate_compliance_id": 1055238,
            "associate_name": "National Iranian Tanker Company",
            "associate_relationship": "Associate",
            "associate_type": "organisation",
            "company_code": 101754,
            "company_name": "NITC",
            "compliance_company_name": "N.I.T.C. Representative Office",
            "compliance_id": 138233,
            "id": 9677746,
            "ignored": false,
            "resource_uri": "/api/v1/companysanction/9677746",
            "sanction_name": "DFAT (Australia) Specified Entities List",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "OK",
            "ship_relationship": null,
            "since_date": "2010-07-29",
            "to_date": "2016-01-18"
        }
    ]
}

A vessel with a long compliance history produces a long list. This one runs to 59 records, so page through with limit and offset or follow meta.next.

objects comes back empty when no company or associate is on a watchlist.

Country watchlist results

GET /countrycheck takes the same COMPANY_SANCTIONS id and returns the country side of the check. Five company roles are covered:

Group beneficial owner

Registered owner

Ship manager

Technical manager

Operator

Each role is checked against three countries: control, registration and domicile. You get one object for every combination that produces a watchlist hit, which is why a single sanctioned operator can generate several records.

{
    "meta": {
        "limit": 10,
        "next": "/api/v1/countrycheck?screenresult=14837196&api_key=&username=&limit=10&offset=10",
        "offset": 0,
        "previous": null,
        "total_count": 30
    },
    "objects": [
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "DOMICILE_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.131242",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "OPERATOR",
            "id": 73388316,
            "resource_uri": "/api/v1/countrycheck/73388316",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "CONTROL_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.132673",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "OPERATOR",
            "id": 73388317,
            "resource_uri": "/api/v1/countrycheck/73388317",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "REGISTRATION_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.134037",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "OPERATOR",
            "id": 73388318,
            "resource_uri": "/api/v1/countrycheck/73388318",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "DOMICILE_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.135394",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "GROUP_BENEFICIAL_OWNER",
            "id": 73388319,
            "resource_uri": "/api/v1/countrycheck/73388319",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "CONTROL_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.136770",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "GROUP_BENEFICIAL_OWNER",
            "id": 73388320,
            "resource_uri": "/api/v1/countrycheck/73388320",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "REGISTRATION_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.138119",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "GROUP_BENEFICIAL_OWNER",
            "id": 73388321,
            "resource_uri": "/api/v1/countrycheck/73388321",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "DOMICILE_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.139551",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "SHIP_MANAGER",
            "id": 73388322,
            "resource_uri": "/api/v1/countrycheck/73388322",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "CONTROL_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.140951",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "SHIP_MANAGER",
            "id": 73388323,
            "resource_uri": "/api/v1/countrycheck/73388323",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "REGISTRATION_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.142363",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "SHIP_MANAGER",
            "id": 73388324,
            "resource_uri": "/api/v1/countrycheck/73388324",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        },
        {
            "company_severity": "CRITICAL",
            "company_watchlist_link": "NITC",
            "country_name": "Iran",
            "country_type": "DOMICILE_COUNTRY",
            "creation_date": "2023-12-05T14:14:35.143778",
            "effective_date": null,
            "entity_name": "NITC",
            "entity_type": "TECHNICAL_MANAGER",
            "id": 73388325,
            "resource_uri": "/api/v1/countrycheck/73388325",
            "screenresult": "/api/v1/screenresult/14837196",
            "severity": "CRITICAL"
        }
    ]
}

company_watchlist_link names the company that carries the country hit, and entity_type says which role it plays. objects comes back empty when no entity is on a watchlist.

Screening Vessels

Registering a vessel, and reading the screen_results ids these checks need.

Additional Checks

The checks that sit alongside the watchlists, including flag and company history.

Errors and Status Codes

What a 400, 401 or 500 means on these endpoints.

Detailed Watchlist Checks

Ship and flag watchlist check#

Find the id#

Retrieve the results#

Company and country watchlist check#

Find the id#

Company watchlist results#

Country watchlist results#

Related#

Ship and flag watchlist check

Find the id

Retrieve the results

Company and country watchlist check

Find the id

Company watchlist results

Country watchlist results

Related