Follow

API documentation

Version 1.0.0

Authentication

Every user-initiated request needs to have a valid Authorization header. The value of the header must be Token token="XXX", where XXX is the user token. See examples below.

REST endpoints

The following endpoints are available:

POST /api/v1/containers

Add a container to your dashboard, which will cause webhooks to be invoked whenever updated information is available about the container.

Request

The request body must be a JSON object of the form {"container": < container-object >, "sandbox_url": "webhook url"}, where < container-object > has the following structure:

Key

Required?

Value

number

required

The container number, e.g. GESU1234567

pod

optional

The port of discharge. If provided, this must be a valid 5-character uppercase port code, e.g. USTIW

vessel_voyage

optional

The vessel name and voyage number, e.g. DUESSELDORF EXPRESS 06W31

shipping_line

optional

The shipping line scac, e.g. MAEU for Maersk

tags

optional

An array of tags that will be saved to the container, e.g. ["foo", "bar"]

sandbox_url is an optional webhook url that can be different than the organization's webhook url. If included, the api will immediately invoke the webhook with fake information after sending the response. Please see below for the format of the webhook request.

Response

On success, the API may respond with a status of 200 OK or 204 No Content. On failure, the API will return:

Status

Reason

Body

400

Missing container number

{"errors": ["Container number is required"]}

400

Invalid container number

{"errors": ["Container number is invalid"]}

400

Invalid port of discharge

{"errors": ["Port of discharge is invalid"]}

 

Example

 

       curl -X POST \
            -H 'Authorization: Token token="XXX"' \
            -H 'Content-type: application/json' \
            -d '{"container": {"number": "XYZZ1234567", "pod": "USTIW", "vessel_voyage": "DUESSELDORF EXPRESS 06W31"}}' \
            https://track.cruxsystems.com/api/v1/containers
   

Webhooks

Outbound webhooks are sent to your application.

Container event webhook

The container event webhook is fired via HTTP POST whenever updated information is available for one of the containers on your dashboard.

Immediately after adding a container to your dashboard, Crux Systems will begin searching for your container and invoke the webhook with event type created. Afterwards, every time the container's status is updated, Crux Systems will invoke your webhook with the event type updated.

If the webhook URL is over HTTPS, an Authorization header will be included. The value of the header will be Token token=”XXX”, where XXX is the user token.

Request

The request body is a JSON object with the following keys:

Key

Description

event_type

Either created (the first time the container is searched) or updated

container

The container status (see below)

vessel

Metadata about the vessel (see below)

terminal

Metadata about the terminal (see below)

 

The container object contains the following keys:

Key

Example

Description

number

GESU1234567

The container number.

status

"available"

One of:

not_manifested: the container that is so early in its lifecycle that the terminal doesn't know about it yet

en_route: the container has not yet arrived at the import terminal

on_ship: the container is on a vessel and is headed to its destination, or waiting to be unloaded at a terminal

not_available: the container is in yard, but not yet available, at the import terminal

available: the container is in yard and available at the import terminal

departed_terminal: the container has departed from the terminal at the port of discharge 

departed_at

"2016-10-29T12:34:56Z"

If applicable, the date and time when the container departed the terminal. Otherwise the value is null.

discharged_at

"2016-10-30T12:34:56Z"

If applicable, the date and time when the container was discharged. Otherwise the value is null.

location

"In Yard (#B004 row) Grounded"

If applicable, the location of the container within the terminal.

demurrage

"240.00"

If applicable, the demurrage amount in USD. Otherwise the value is null.

last_free_day

"2016-10-31"

If applicable, the last free day of the container. Otherwise the value is null. Dates are listed in the same timezone as the terminal.

line_hold

"RELEASED"

The reason for the line hold if the container is subject to a line hold. If all line holds have been released, it has the value "RELEASED". If the hold state is not yet known, the value is null.

customs_hold

"RELEASED"

The reason for the customs hold if the container is subject to a customs hold. If all customs holds have been released, it has the value "RELEASED". If the hold state is not yet known, the value is null.

other_holds

null

Any other holds on the container. If there are no miscellaneous holds, the value is null.

tags

[ "foo", "bar" ]

An array of tags that are saved on the container.

 

The vessel object containers the following keys:

Key

Example

Description

name

MSC NILGUN

If applicable, the name of the vessel. Otherwise the value is null.

eta

"2016-10-29T12:34:56Z"

If applicable, the ETA of the vessel. Otherwise the value is null. ETAs are listed in UTC. An ETA update is provided via the API when there is another status update to report on the container.

ata

"2016-10-29T12:34:56Z"

If applicable, the ATA of the vessel. Otherwise the value is null.

 

The terminal object contains the following keys:

Key

Example

Description

name

Maher Elizabeth

The name of the terminal.

timezone

America/New_York

The Olson TZID for the timezone of the terminal and vessel.

 

Here is a sample webhook request:

     {
       "event_type": "updated",
       "container": {
         "number": "XYZZ1234567",
         "status": "available",
         "discharged_at": "2016-05-06T22:08:00Z",
         "last_free_day": "2016-05-13",
         "departed_at": null,
         "location": "In Yard (#B003 row) Grounded",
         "demurrage": "0.00",
         "line_hold": "RELEASED",
         "customs_hold": "RELEASED",
         "other_holds": null
       },
       "vessel": {
         "name": "ZIM TEXAS",
         "eta": "2016-05-06T14:00:00Z",
         "ata": "2016-05-06T14:00:00Z"
       },
       "terminal": {
         "name": "POHA Bayport Houston",
         "timezone": "America/Chicago"
       }
     }
   

Response

Your endpoint should respond with status 204 and an empty body.

 

Version 1.0.1 Updates

Webhooks

In addition to the attributes available in version 1.0.0, the following attributes will be transmitted. Note that these attributes may be null if the data sources that originate the events do not provide enough information to infer the attributes.

Container Object

Key

Example

Description

bill_of_lading

BL12AF234

The bill of lading associated with the container.

origin

{ "locode" = "USOAK", "info" = "everport-oakland" }

The unlocode and textual representation of the port of origin

port_of_loading

{ "locode" = "USOAK", "info" = "everport-oakland" }

The unlocode and textual representation of the port where the container was last loaded into the vessel (i.e. different from the origin in case of trans-shipment

destination

{ "locode" = "USOAK", "info" = "everport-oakland" }

The unlocode and textual representation of the port of destination

 

Version 1.0.2 Updates:

Webhooks

In addition to the attributes available in version 1.0.1, the following attributes will be transmitted. Note that these attributes may be null if the data sources that originate the events do not provide enough information to reliably infer it.

General:

Key

Example

Description

as_of

"2016-10-29T12:34:56Z"

A timestamp of when the information of the event is obtained. The value is either the timestamp provided by the data source, or the timestamp of when the information is available to Crux Systems if the data sources do not provide a reliable value.

 

Container Object:

Key

Example

Description

firms_code

W778

The four character identifier of the facility in US Customs DB.

geolocation

{ "lat" : 37.4224764, "lng" : -122.0842499 }

The current latitude and longitude of the container.

origin

{ "locode" = "USOAK", "info" = "everport-oakland" "TZ" = "America/Los_Angeles" }

Adding the timezone name according to iana.org of the port of origin.

port_of_loading

{ "locode" = "USOAK", "info" = "everport-oakland" "TZ" = "America/Los_Angeles" }

Adding the timezone name according to iana.org of the last port of loading.

destination

{ "locode" = "USOAK", "info" = "everport-oakland" "TZ" = "America/Los_Angeles" }

Adding the timezone name according to iana.org of the port of destination.

events

[
{
"category": "string",
"event": "string",
"occurred_at": "2019-04-15T00:00:00Z",
"occurred_status": "string"
}
]

An array of events associated with the container.

The category indicates whether the event is a container lifecycle or a workflow (user generated events). Initially only lifecycle events will be reported.

The event describes what action or state change affected the container.

"Occurred at" provides the timestamp of when the event occurred.

"Occurred_status": defines whether the event is estimated (to happen in the future) or actual (already past).

The vessel object adds the following keys:

Key

Example

Description

name

<>

The vessel name

eta

2016-06-05T00:00:00Z

Estimated time of arrival

ata

2016-06-05T00:00:00Z

 Actual time of arrival

 

Terminal Object

The terminal object adds the following keys:

Key

Example

Description

name

Maher Elizabeth

 The name of the terminal

unloccode

USOAK

The UN Location Code for the port

 timezone

 America/Los Angeles

 The timezone where the terminal is located

 

Events

The information also contains an array of events with the following information:

Key

Example/type

Description

category

lifecycle, workflow

The type of event, either lifecycle or workflow events

event

lifecycle_discharge

The event that the shipment experienced

location_locode

THLCH

The locode where the event took place if available

location_terminal_cruxid

<alpha-numerical>

A unique identifier of the terminal where the event took place, if available

location_text

Burlingame, USA

A text description of the location where the event took place, if available

occurred_at

timestamp

Timestamp of when the event takes place

occurred_date

date

Calendar day when the event takes place

occurred_status

actual or estimate

Whether the event occurred in the past (actual) or it is estimated it will occur in the future (estimate)

occurred_time

time

Time when the event takes place

transit_mode

rail, ship, truck

The transportation mode that generated the event if applicable

transit_scac

SCAC

SCAC code for the transportation mode

transit_text

text

Textual representation of the transportation mode

transit_vessel_imo

IMO number

IMO of the vessel if applicable

 

Example 

A full example of the information provided:

{
  "event_type": "updated",
  "container": {
    "number": "ACLU9789590",
    "status": "available",
    "discharged_at": "2019-04-20T20:18:04Z",
    "last_free_day": "2019-04-27",
    "departed_at": null,
    "location": "YARD",
    "demurrage": 0,
    "line_hold": "RELEASED",
    "customs_hold": "RELEASED",
    "other_holds": "",
    "bill_of_lading": "SA00373466",
    "firms_code": "S787",
    "origin": {
      "locode": null,
      "info": null
    },
    "port_of_loading": {
      "locode": "DEHAM",
      "info": "HAMBURG"
    },
    "destination": {
      "locode": null,
      "info": null
    },
    "tags": []
  },
  "vessel": {
    "name": "CHARLESTON EXPRESS",
    "eta": "2019-04-19T08:00:00Z",
    "ata": "2019-04-19T10:36:00Z"
  },
  "terminal": {
    "name": "POHA Barbours Cut Houston",
    "locode": "USHOU",
    "timezone": "America/Chicago"
  },
  "events": [
    {
      "category": "lifecycle",
      "event": "lifecycle_discharge",
      "location_locode": "USHOU",
      "location_terminal_cruxid": "USHOU-BCT",
      "location_text": "HOUSTON",
      "location_time_zone": "America/Chicago",
      "occurred_at": "2019-04-20T20:18:04Z",
      "occurred_date": "2019-04-20",
      "occurred_status": "actual",
      "occurred_time": "15:18:04",
      "transit_mode": "ship",
      "transit_scac": "ACLU",
      "transit_text": "CNE-067E",
      "transit_vessel_imo": "9243162"
    },
    {
      "category": "lifecycle",
      "event": "lifecycle_arrival",
      "location_locode": "USHOU",
      "location_terminal_cruxid": null,
      "location_text": "HOUSTON",
      "location_time_zone": "America/Chicago",
      "occurred_at": "2019-04-19T14:06:00Z",
      "occurred_date": "2019-04-19",
      "occurred_status": "estimated",
      "occurred_time": "09:06:00",
      "transit_mode": "ship",
      "transit_scac": "ACLU",
      "transit_text": "CHARLESTON EXPRESS ",
      "transit_vessel_imo": "9243162"
    }
  ]
}

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments