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 not even the shipping line knows 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 the terminal

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.

The vessel object adds the following keys:

Key

Example

Description

IMO

9231157

The IMO code for the vessel.

MSSI

229481000

The MSSI Code for the vessel.

 

Terminal Object

The terminal object adds the following keys:

Key

Example

Description

unloccode

USOAK

The UN Location Code for the port.

 

 

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

Comments