Bill of lading verification

BL Verification screens a bill of lading and returns the voyage behind it. The carrier, every vessel carrying the cargo and every port on the route come back with a severity, set against your account's screening settings. Once a bill of lading is screened you can track it, and PurpleTRAC then reports voyage and compliance events until the cargo reaches its destination.

BL Verification is an addon

We enable BL Verification per account. A 403 on the screening, tracking and reporting 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 the bill of lading

POST /blv takes the bill of lading number and the carrier's SCAC code. client_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" when you do not know which code to use. We detect the carrier while the bill of lading is screened and return its SCAC in the results. If no carrier can be identified, scac stays AUTO. Bill of Lading Carriers lists the codes we support.

The response confirms the submission and carries the id:

{
    "archived": false,
    "blv_no": "ISB1235295",
    "blv_phase_status": "SCREEN",
    "client_reference": "",
    "creation_date": "2023-12-11 14:40:27.171665+00:00",
    "id": 35260,
    "is_trackable": true,
    "last_screening_result": {
        "carrier_severity": "PENDING",
        "details": {},
        "id": 38353,
        "overall_severity": "PENDING",
        "port_of_destination": null,
        "port_of_origin": null,
        "screened_ports": [],
        "screened_ships": [],
        "screening_date": "2023-12-11T14:40:27.178234",
        "screening_status": "SCREENING"
    },
    "notifications": [],
    "num_notifications": 0,
    "overall_severity": "PENDING",
    "resource_uri": "/api/v1/blv/35260",
    "scac": "CMDU",
    "scac_name": "CMA CGM",
    "screening_status": "SCREENING",
    "ship_transactions": []
}

Store id. The results, the reports and tracking all take it.

Read the screening results

GET /blv/{id} returns both the screening status and the results, so you poll and read through the same call.

screening_status tells you whether the results are final.

Value	Means
`SEARCHING`	The provider is looking the bill of lading up
`SCREENING`	Vessel, port and carrier screening is running
`SCREENING_COMPLETED`	Every check has finished, and `overall_severity` is final
`NOT_FOUND`	The provider holds no record of that bill of lading

How long screening takes depends on how many vessels the bill of lading covers, because each one is screened in its own right.

A second field, blv_phase_status, tracks the lifecycle rather than the screening run: SCREEN while it is being screened, TRACK once you enable tracking, and ARCHIVE once tracking is declined or the bill of lading is archived.

{
    "archived": false,
    "archived_date": null,
    "blv_no": "ISB1235295",
    "blv_phase_status": "SCREEN",
    "client_reference": "",
    "creation_date": "2023-12-11 14:40:27.171665+00:00",
    "id": 35260,
    "is_trackable": true,
    "is_live_trackable": false,
    "last_screening_result": {
        "carrier_severity": "OK",
        "details": {
            "cargo": {
                "containers_no": [
                    "CMAU8752246"
                ]
            },
            "container_numbers": [
                "CMAU8752246"
            ],
            "ordered_port_unlocodes": [
                "TRMER",
                "EGALY"
            ],
            "voyages": [
                {
                    "arrival_port": {
                        "city": "Alexandria, Egypt",
                        "country": "Egypt",
                        "estimated_time": "11.03.2023 15:00",
                        "unlocode": "EGALY"
                    },
                    "departure_port": {
                        "city": "Mersin, Turkey",
                        "country": "Turkey",
                        "estimated_time": "05.03.2023 04:24",
                        "unlocode": "TRMER"
                    },
                    "imo_number": 9311842,
                    "is_custom": false,
                    "mode": "Unknown",
                    "seq": 1,
                    "transport_name": "SC MONTANA"
                }
            ]
        },
        "id": 38353,
        "overall_severity": "WARNING",
        "port_of_destination": {
            "code": "EGALY",
            "name": "Alexandria, Egypt"
        },
        "port_of_origin": {
            "code": "TRMER",
            "name": "Mersin, Turkey"
        },
        "screened_ports": [
            {
                "code": "TRMER",
                "country": {
                    "code": "TUR",
                    "iso_3166_1_alpha_2": "TR",
                    "name": "Turkey"
                },
                "name": "Mersin",
                "overall_severity": "OK",
                "seq": 0
            },
            {
                "code": "EGALY",
                "country": {
                    "code": "EGY",
                    "iso_3166_1_alpha_2": "EG",
                    "name": "Egypt"
                },
                "name": "Alexandria",
                "overall_severity": "OK",
                "seq": 1
            }
        ],
        "screened_ships": [
            {
                "document_id": 4932934,
                "flag": {
                    "code": "LBR",
                    "iso_3166_1_alpha_2": "LR",
                    "name": "Liberia"
                },
                "imo_number": "9311842",
                "overall_severity": "WARNING",
                "seq": 0,
                "ship_name": "SC MONTANA",
                "transaction_id": 2863260
            }
        ],
        "screening_date": "2023-12-11T14:40:27.178234",
        "screening_status": "SCREENING_COMPLETED"
    },
    "notifications": [
        {
            "id": 52697508,
            "creation_date": "2023-12-11T14:40:54.096909+00:00",
            "document_id": null,
            "event": {
                "name": "BLV_SCREENING_COMPLETE"
            }
        }
    ],
    "num_notifications": 1,
    "overall_severity": "WARNING",
    "resource_uri": "/api/v1/blv/35260",
    "scac": "CMDU",
    "scac_name": "CMA CGM",
    "screening_status": "SCREENING_COMPLETED",
    "ship_transactions": [
        "/api/v1/transaction/2863260"
    ]
}

Each entry in screened_ships carries a transaction_id. That is a full vessel screening transaction, so you can take any of those ids to the vessel endpoints and read the watchlist checks and movement history behind the severity shown here. Screening Vessels covers what those endpoints return.

Every bill of lading on the account

GET /blv returns the same objects as an array, wrapped in a pagination envelope.

Each object in objects has the shape shown above. The first one here has a screening_status of NOT_FOUND, which is what you get when the provider cannot find the bill of lading at all.

{
  "meta": {
    "limit": 3,
    "next": "/api/v1/blv?api_key=&username=&limit=3&offset=3",
    "offset": 0,
    "previous": null,
    "total_count": 5
  },
  "objects": [
    {
      "archived": false,
      "archived_date": null,
      "blv_no": "MEDU11111111",
      "blv_phase_status": "SCREEN",
      "client_reference": null,
      "creation_date": "2022-05-23 11:30:03.097275+00:00",
      "id": 13523,
      "is_trackable": false,
      "is_live_trackable": false,
      "last_screening_result": {
        "carrier_severity": "PENDING",
        "details": {},
        "id": 13492,
        "overall_severity": "PENDING",
        "port_of_destination": null,
        "port_of_origin": null,
        "screened_ports": [],
        "screened_ships": [],
        "screening_date": "2022-10-25T15:04:05.838723",
        "screening_status": "NOT_FOUND"
      },
      "notifications": [],
      "num_notifications": 0,
      "overall_severity": "PENDING",
      "resource_uri": "/api/v1/blv/13523",
      "scac": "MSCU",
      "scac_name": "MSC Mediterranean Shipping Co",
      "screening_status": "NOT_FOUND",
      "ship_transactions": []
    }
  ]
}

The screening report

GET /blv_report returns the PurpleTRAC screening report as a PDF, once screening has completed. The id goes in the blv_id query parameter rather than the path.

Track the bill of lading

Tracking follows screening, the same way it does for a vessel. You keep the same id throughout.

Enable tracking

PUT /blv/{id}/track with an empty body.

You get the screening result object back, unchanged apart from the phase and a new notification confirming the bill of lading is now tracked:

{
    "blv_phase_status": "TRACK",
    "notifications": [
        {
            "id": 52699269,
            "creation_date": "2023-12-11T15:36:00.116953+00:00",
            "document_id": null,
            "event": {
                "name": "BL_SELECTED_FOR_TRACKING"
            }
        }
    ],
    "num_notifications": 2
}

Read notifications

GET /notification serves bill of lading events from the same endpoint as vessel events. Pass the bill of lading id in the blv query parameter.

Which events you receive, and what severity each one carries, comes from your account's notification settings. Your account admin edits those in the PurpleTRAC UI.

{
    "meta": {
        "limit": 10,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 2
    },
    "objects": [
        {
            "acknowledged": false,
            "blv": "/api/v1/blv/35260",
            "cleared": false,
            "comment": "",
            "creation_date": "2023-12-11T15:36:00.116953+00:00",
            "document_id": null,
            "event": "BL_SELECTED_FOR_TRACKING",
            "event_date": "2023-12-11T15:36:00.111687+00:00",
            "id": 52699269,
            "last_updated_date": "2023-12-11T15:36:00.116977+00:00",
            "parent_notification_id": null,
            "related_obj_id": null,
            "related_text": "",
            "resource_uri": "/api/v1/notification/52699269",
            "severity": "OK",
            "transaction": null,
            "updated_since_creation": false,
            "user": "/api/v1/user/6913"
        },
        {
            "acknowledged": false,
            "blv": "/api/v1/blv/35260",
            "cleared": false,
            "comment": "",
            "creation_date": "2023-12-11T14:40:54.096909+00:00",
            "document_id": null,
            "event": "BLV_SCREENING_COMPLETE",
            "event_date": "2023-12-11T14:40:54.094287+00:00",
            "id": 52697508,
            "last_updated_date": "2023-12-11T14:40:54.096934+00:00",
            "parent_notification_id": null,
            "related_obj_id": null,
            "related_text": "",
            "resource_uri": "/api/v1/notification/52697508",
            "severity": "OK",
            "transaction": null,
            "updated_since_creation": false,
            "user": "/api/v1/user/6913"
        }
    ]
}

A newly tracked bill of lading can have nothing to report for a while, so an empty objects array early on is expected.

Stop tracking

Tracking stops on its own when the bill of lading reaches its final destination, and the bill of lading is archived at the same moment. To stop it earlier, call PUT /blv/{id}/decline.

The screening result comes back with the archive fields set and a closing notification:

{
    "archived": true,
    "archived_date": "2023-12-11T15:52:48.000000+00:00",
    "blv_phase_status": "ARCHIVE",
    "is_trackable": false,
    "notifications": [
        {
            "id": 52699824,
            "creation_date": "2023-12-11T15:52:48.757522+00:00",
            "document_id": null,
            "event": {
                "name": "BL_TRACKING_COMPLETED"
            }
        }
    ],
    "num_notifications": 3
}

Collect the tracking report

Once the bill of lading is archived, by your request or on arrival, GET /blv_tracking_report returns a PDF holding the final screening result and every tracking notification raised along the way.

Bill of Lading Carriers

The SCAC codes we screen bills of lading for.

Container Screening

The same workflow for a single container.

Errors and Status Codes

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

Bill of Lading Verification

Screen the bill of lading#

Read the screening results#

Every bill of lading on the account#

The screening report#

Track the bill of lading#

Enable tracking#

Read notifications#

Stop tracking#

Collect the tracking report#

Related#