Container screening

Container screening takes a single container number and returns the journey it is on. You get the schedule, the vessels that carry it, the ports it passes through, and a severity on each drawn from your account's screening settings.

Container Screening is an addon

We enable container screening per account. A 403 on any of the endpoints below means the addon is not on your contract, so ask your Pole Star representative to add it. A 401 means your credentials are wrong.

Screen a container

POST /containers takes the container number and the carrier's SCAC code. A container number is four letters followed by seven digits. container_reference is optional freeform text, and it comes back in the screening results and in the PDF report.

Let PurpleTRAC find the carrier

Send "scac": "AUTO", or leave the field blank, when you do not know which code to use. We detect the carrier while the container is screened and return its SCAC. If no carrier can be identified, scac stays AUTO. Container Carriers lists the codes we support.

The response carries a container_screen_id:

{
  "container_screen_id": "8183da12-988f-4401-bc3f-3e64b451e654",
  "scac": "MAEU",
  "container_number": "MRKU1234567",
  "container_reference": "User defined reference field",
  "creation_date": "2023-07-19T11:06:51.482652516Z"
}

A container screen id is not a transaction id

Vessel and bill of lading screening return a numeric transaction_id. Container screening returns a container_screen_id, a UUID, and the container endpoints take that. The two ids are not interchangeable.

Read the screening results

GET /containers/{id} returns the screening status and the results together, so you poll and read through the same call. You can call it as soon as the id comes back.

While the screening runs, screening_status reads PENDING. It changes to SCREENING_COMPLETED when the results are ready to use. Most screenings finish within a few seconds, and in rare cases one takes up to two minutes.

{
    "container_screen_id": "8183da12-988f-4401-bc3f-3e64b451e654",
    "scac": "MAEU",
    "container_number": "MRKU1234567",
    "container_reference": "freeform custom reference field",
    "creation_date": "2023-11-28 12:28:22",
    "container_phase": "SCREEN",
    "screening_status": "SCREENING_COMPLETED",
    "overall_severity": "CRITICAL",
    "carrier_name": "Maersk",
    "carrier_severity": "CRITICAL",
    "port_of_loading": {
        "code": "AUADL",
        "name": "Adelaide",
        "state": "State of South Australia",
        "country": "Australia"
    },
    "port_of_discharge": {
        "code": "USOAK",
        "name": "Oakland",
        "state": "California",
        "country": "United States"
    },
    "screened_ports": [
        {
            "code": "AUADL",
            "country_code": "AUS",
            "name": "Adelaide",
            "severity": "OK"
        },
        {
            "code": "USOAK",
            "country_code": "USA",
            "name": "Oakland",
            "severity": "OK"
        }
    ],
    "ship_transactions": [
        {
            "id": "2836479",
            "imo_number": "9698252",
            "vessel_name": "WIDE INDIA",
            "vessel_severity": "WARNING",
            "flag_code": "MHL",
            "screen_results": [
                {
                    "check": "COMPANY_SANCTIONS",
                    "status": "OK"
                },
                {
                    "check": "PSC_HISTORY",
                    "status": "OK"
                },
                {
                    "check": "SANCTIONS",
                    "status": "OK"
                },
                {
                    "check": "SHIP_MOVE_HIST",
                    "status": "WARNING"
                }
            ]
        }
    ],
    "container_events": [
        {
            "journey_event_type": "Equipment",
            "equipment_event_type": "GTIN",
            "transport_event_type": "",
            "event_description": "Gate in",
            "event_datetime": "2023-10-20 21:09:00",
            "event_classifier": "Actual",
            "transport_mode": "Truck or rail",
            "empty_indicator": "",
            "facility_type": "",
            "location_name": "Adelaide",
            "location_country": "Australia",
            "unlocode": "AUADL",
            "location_severity": "OK",
            "imo_number": "",
            "vessel_name": "",
            "vessel_severity": null,
            "is_custom": false
        },
        {
            "journey_event_type": "Equipment",
            "equipment_event_type": "LOAD",
            "transport_event_type": "",
            "event_description": "Load",
            "event_datetime": "2023-10-29 00:37:00",
            "event_classifier": "Actual",
            "transport_mode": "Vessel",
            "empty_indicator": "",
            "facility_type": "",
            "location_name": "Adelaide",
            "location_country": "Australia",
            "unlocode": "AUADL",
            "location_severity": "OK",
            "imo_number": "9698252",
            "vessel_name": "WIDE INDIA",
            "vessel_severity": "WARNING",
            "is_custom": false
        },
        {
            "journey_event_type": "Transport",
            "equipment_event_type": "",
            "transport_event_type": "DEPA",
            "event_description": "Vessel departure",
            "event_datetime": "2023-10-29 06:10:00",
            "event_classifier": "Actual",
            "transport_mode": "Vessel",
            "empty_indicator": "",
            "facility_type": "",
            "location_name": "Adelaide",
            "location_country": "Australia",
            "unlocode": "AUADL",
            "location_severity": "OK",
            "imo_number": "9698252",
            "vessel_name": "WIDE INDIA",
            "vessel_severity": "WARNING",
            "is_custom": false
        },
        {
            "journey_event_type": "Transport",
            "equipment_event_type": "",
            "transport_event_type": "ARRI",
            "event_description": "Vessel arrival",
            "event_datetime": "2023-11-30 17:00:00",
            "event_classifier": "Estimated",
            "transport_mode": "Vessel",
            "empty_indicator": "",
            "facility_type": "",
            "location_name": "Oakland",
            "location_country": "United States",
            "unlocode": "USOAK",
            "location_severity": "OK",
            "imo_number": "9698252",
            "vessel_name": "WIDE INDIA",
            "vessel_severity": "WARNING",
            "is_custom": false
        },
        {
            "journey_event_type": "Equipment",
            "equipment_event_type": "DISC",
            "transport_event_type": "",
            "event_description": "",
            "event_datetime": null,
            "event_classifier": "Estimated",
            "transport_mode": "Vessel",
            "empty_indicator": "",
            "facility_type": "",
            "location_name": "Oakland",
            "location_country": "United States",
            "unlocode": "USOAK",
            "location_severity": "OK",
            "imo_number": "9698252",
            "vessel_name": "WIDE INDIA",
            "vessel_severity": "WARNING",
            "is_custom": true
        },
        {
            "journey_event_type": "Equipment",
            "equipment_event_type": "GTOT",
            "transport_event_type": "",
            "event_description": "",
            "event_datetime": null,
            "event_classifier": "Estimated",
            "transport_mode": "Truck or rail",
            "empty_indicator": "",
            "facility_type": "",
            "location_name": "Oakland",
            "location_country": "United States",
            "unlocode": "USOAK",
            "location_severity": "OK",
            "imo_number": "",
            "vessel_name": "",
            "vessel_severity": null,
            "is_custom": true
        }
    ]
}

Two fields in there repay a second look.

event_classifier separates what has happened from what is expected. An Actual event has taken place; an Estimated one has not, and its event_datetime can still be null. Alongside it, is_custom marks the events PurpleTRAC has inferred to complete the journey rather than received from the carrier.

Each entry in ship_transactions carries an id, which is a vessel screening transaction. Take it to the vessel endpoints to read the watchlist checks and movement history behind the screen_results summary shown here. Screening Vessels covers those.

The screening report

GET /containers/{id}/report returns the PurpleTRAC PDF screening report, using the same container_screen_id.

Every container on the account

GET /containers returns the same objects as an array. Four optional query parameters narrow it: container_number, container_reference, overall_severity and scac.

The envelope carries item_count and the next_link and prev_link pair for paging. The entry below is cut short: every item in items holds the full set of fields from the single result, screened_ports, ship_transactions and container_events included.

{
    "item_count": 3,
    "next_link": null,
    "prev_link": null,
    "items": [
        {
            "container_screen_id": "5f39a8c3-8710-4448-a88d-c47aaa61a39d",
            "scac": "MAEU",
            "container_number": "MRKU1234567",
            "container_reference": "freeform custom reference field",
            "creation_date": "2023-11-16 08:50:54",
            "container_phase": "SCREEN",
            "screening_status": "SCREENING_COMPLETED",
            "overall_severity": "CRITICAL",
            "carrier_name": "Maersk",
            "carrier_severity": "CRITICAL"
        }
    ]
}

Archive a container screening

Archiving moves container_phase from SCREEN to ARCHIVE and nothing else. No information is removed, and you can still read the results and the report afterwards. It keeps active work separate from finished work, which makes filtering easier once you have screened a few hundred containers.

The response repeats the confirmation you got when the screening was created.

{
  "container_screen_id": "8183da12-988f-4401-bc3f-3e64b451e654",
  "scac": "MAEU",
  "container_number": "MRKU1234567",
  "container_reference": "User defined reference field",
  "creation_date": "2023-07-19T11:06:51.482652516Z"
}

Container Carriers

The SCAC codes we screen containers for.

Bill of Lading Verification

The same workflow across a whole bill of lading, with tracking.

Errors and Status Codes

What each status code means, and the response shapes you will meet.

Screen a container#

Read the screening results#

The screening report#

Every container on the account#

Archive a container screening#

Related#

Screen a container

Read the screening results

The screening report

Every container on the account

Archive a container screening

Related