Containers
This resource allows you to interact with containers in Octopi.

In Octopi, a container object can represent a container, but sometimes can also represent non-containerized cargo such as break-bulk cargo, cars, boats, etc.

When a container object has a number, it is a container. When the number is left blank, it represents another type of cargo such as vehicle, breakbulk, boat, etc.

Containers have many movements. A movement can be a Gate In, Gate Out, Full Stripping, Container Damage, Unloading, etc.

Supported Formats

json
>>>

GET /api/v1/containers.json
Returns information about containers.

Supported Formats

json

Errors

Code Description
404 Not Found: one of the requested resources wasn't found.
422 Unprocessable Entity: unable to process request due to an input or validation error.
500 Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/containers.json" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=YOURTOKEN"

{
  "containers": [
    "container": {
      "id": "123456",
      "number": "BMOU4286229",
      "bill_of_lading": "PEV1231231",
      "status": "full",
      "size": "20",
      "container_type": {
        "label": "20RF",
        "description": "This is a 20 ft. container",
        "iso_type_code": "22RF"
      },
      "is_high_cube": false,
      "is_reefer": true,
      "seals": [
        "G3117839",
        "DGAEXP"
      ],
      "return_temperature": 10,
      "supply_temperature": 10,
      "set_point_temperature": 10,
      "temperature_unit": "F",
      "arrival_voyage": {
        "number": "2345",
        "vessel": {
          "name": "Vega Luna",
          "estimated_time_of_anchorage": "2017-04-07T02:00:00.000Z"
        }
      },
      "commodity_type": {
        "name": "Fish"
      },
      "departure_voyage": {
        "number": "2345",
        "vessel": {
          "name": "Vega Luna",
          "estimated_time_of_anchorage": "2017-05-07T02:00:00.000Z"
        }
      },
      "weight": 100.0,
      "container_vgm": {
        "weight": 100.0,
        "created_at": "2017-04-07T02:00:00.000Z",
        "user": {
          "name": "John D."
        }
      },
      "usage": "import",
      "shipping_line": {
        "code": "MASL",
        "name": "Ma Shipping Line",
        "carrier_type": "Ocean",
        "agent": {
          "name": "John Doe"
        }
      },
      "consignees": [
        {
          "name": "SODIPAL SA"
        }
      ],
      "meets_iso_standards": true,
      "goods": "TOILET TISSUEHS CODE  481810",
      "current_location_type": "Terminal",
      "current_location": "Terminal: South Terminal",
      "yard_area": {
          "id": 2,
          "name": "GRID 3328",
          "description": "",
          "terminal_id": 1,
          "area_type": "grid"
      },
      "yard_slot": {
          "id": 6,
          "name": "GRID 3328",
          "description": "",
          "terminal_id": 1,
          "area_type": "grid",
          "custom_name": "GD1A2"
      },
      "iso_standards_errors": "",
      "hazmat_codes": [
        {
          "code": "12XV",
          "description": "hazmat",
          "name": "Hextol",
          "hazmat_class": {
            "name": "Explosives",
            "description": "Explosives that have a projection hazard but not a mass explosion hazard.",
            "class_number": 1,
            "division_number": 2
          }
        }
      ],
      "over_height": false,
      "over_length": false,
      "over_width": false,
      "is_out_of_gauge": false,
      "actions": {
        "show": {
          "url": "https://app.octopi.co/api/v1/containers/BMOU4286229.json",
          "method": "GET"
        },
        "flex_fields": [
          {
            "label": "Name",
            "value": "Octopi"
          }
        ]
      }
    }
  ],
  "actions": {
    "index": {
      "method": "GET",
      "url": "https://app.octopi.co/api/v1/containers.json"
    },
    "next": {
      "method": "GET",
      "url": "https://app.octopi.co/api/v1/containers.json?page=2"
    },
    "previous": {
      "method": "GET",
      "url": "https://app.octopi.co/api/v1/containers.json?page=0"
    },
    "last": {
      "method": "GET",
      "url": "https://app.octopi.co/api/v1/containers.json?page=304"
    }
  }
}

Params

Param name Description
container_type_id
optional

Filter for a specific container type. Can be the Octopi container type id or container type label.

Validations:

  • Must be a String
shipping_line_id
optional

Filter for a specific shipping line. Can be the Octopi shipping line id or shipping line name.

Validations:

  • Must be a String
current_location_type
optional

Filter for a specific current location type.

Validations:

  • Must be a String
current_location_id
optional

Filter for a specific current location id.

Validations:

  • Must be a String
usage
optional

Filter for a specific usage.

Validations:

  • Must be a String
booking_id
optional

Filter for a specific booking. Can be the Octopi booking id or booking number.

Validations:

  • Must be a String
bill_of_lading_id
optional

Filter for a specific bill of lading. Can be the Octopi bill of lading id or bill of lading number.

Validations:

  • Must be a String
status
optional

Filter for container status (‘full’ or ‘empty’)

Validations:

  • Must be a String
tags
optional

Filter for a list of pipe-separated tags (eg. ‘tag1|tag2|tag3’)

Validations:

  • Must be a String
arrival_voyage_id
optional

Filter for a specific arrival voyage. Can be the Octopi voyage id or voyage number.

Validations:

  • Must be a String
departure_voyage_id
optional

Filter for a specific departure voyage.

Validations:

  • Must be a String
yard_area_id
optional

Filter for a specific yard area.Can be the Octopi yard area id or name.

Validations:

  • Must be a String
page
optional

Specify which page of results to fetch. This value defaults to 1.

Validations:

  • Must be a Integer
per
optional

The number of items to be displayed. This value defaults to 10 and accepts a maximum of 100.

Validations:

  • Must be a Integer
>>>

GET /api/v1/containers/:number.json
Returns information about the container.

Supported Formats

json

Errors

Code Description
404 Not Found: one of the requested resources wasn't found.
422 Unprocessable Entity: unable to process request due to an input or validation error.
500 Internal Server Error.

Examples

Returns information about the container with the matching NUMBER.

curl "https://app.octopi.co/api/v1/containers/CONTAINER_NUMBER.json" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=YOURTOKEN"

{
  "container": {
    "id": "123456",
    "number": "BMOU4286229",
    "bill_of_ladings": ["PEV1231231"],  // Returns list of Active BL's when container usage is import.
    "booking": "BOOK123", // Returns Active Booking number when container usage is export/transshipment.
    "status": "full",
    "size": "20",
    "container_type": {
      "label": "20RF",
      "description": "This is a 20 ft. container",
      "iso_type_code": "22RF"
    },
    "is_high_cube": false,
    "is_reefer": true,
    "seals": [
      "G3117839",
      "DGAEXP"
    ],
    "return_temperature": 10,
    "supply_temperature": 10,
    "set_point_temperature": 10,
    "temperature_unit": "F",
    "arrival_voyage": {
      "number": "2345",
      "vessel": {
        "name": "Vega Luna",
        "estimated_time_of_anchorage": "2017-04-07T02:00:00.000Z"
      }
    },
    "commodity_type": {
      "name": "Fish"
    },
    "departure_voyage": {
      "number": "2345",
      "vessel": {
        "name": "Vega Luna",
        "estimated_time_of_anchorage": "2017-05-07T02:00:00.000Z"
      }
    },
    "weight": 100.0,
    "container_vgm": {
      "weight": 100.0,
      "created_at": "2017-04-07T02:00:00.000Z",
      "user": {
        "name": "John D."
      }
    },
    "usage": "import",
    "shipping_line": {
      "code": "MASL",
      "name": "Ma Shipping Line",
      "carrier_type": "Ocean",
      "agent": {
        "name": "John Doe"
      }
    },
    "consignees": [
      {
        "name": "SODIPAL SA"
      }
    ],
    "meets_iso_standards": true,
    "goods": "TOILET TISSUEHS CODE  481810",
    "current_location_type": "Terminal",
    "current_location": "Terminal: South Terminal",
    "yard_area": {
        "id": 2,
        "name": "GRID 3328",
        "description": "",
        "terminal_id": 1,
        "area_type": "grid"
    },
    "yard_slot": {
        "id": 6,
        "name": "GRID 3328",
        "description": "",
        "terminal_id": 1,
        "area_type": "grid",
        "custom_name": "GD1A2"
    },
    "iso_standards_errors": "",
    "hazmat_codes": [
      {
        "code": "12XV",
        "description": "hazmat",
        "name": "Hextol",
        "hazmat_class": {
          "name": "Explosives",
          "description": "Explosives that have a projection hazard but not a mass explosion hazard.",
          "class_number": 1,
          "division_number": 2
        }
      }
    ],
    "over_height": false,
    "over_length": false,
    "over_width": false,
    "is_out_of_gauge": false,
    "actions": {
      "show": {
        "url": "https://app.octopi.co/api/v1/containers/BMOU4286229.json",
        "method": "GET"
      },
      "flex_fields": [
        {
          "label": "Name",
          "value": "Octopi"
        }
      ]
    }
  }
}

Params

Param name Description
number
required

The container number to locate.

Validations:

  • Must be a String
>>>

POST /api/v1/containers
Creates a container not currently at the terminal

Supported Formats

json

Errors

Code Description
404 Not Found: one of the requested resources wasn't found.
422 Unprocessable Entity: unable to process request due to an input or validation error.
500 Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/containers.json" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token token=YOUR TOKEN HERE" \
  -d '{ \
    "container": {
      "container_type_id": 256,
      "current_location_id": 35,
      "current_location_type": "Terminal",
      "number": "BHCU4942000",
      "shipping_line_id": 78,
      "usage": "unknown",
      "status": "full",
      "cargo_type": "container",
      "pin": "999999",
      "flex_fields": [
        { "container_flex_field_1": "ABC123" },
        { "container_flex_field_2": "XYZ456" }
      ]
    }
  }'

{
  "container": {
    "meets_iso_standards": true,
    "id": 2262336,
    "number": "BHCU4942000",
    "container_type": {
      "code": "40CT",
      "description": "",
      "iso_type_code": "42G1"
    },
    "size": 40,
    "is_high_cube": false,
    "is_reefer": false,
    "seals": [],
    "return_temperature": null,
    "supply_temperature": null,
    "set_point_temperature": null,
    "temperature_unit": "F",
    "arrival_voyage": {
      "number": null,
      "estimated_time_of_anchorage": null,
      "vessel": {
        "name": null
      }
    },
    "commodity_type": {
      "name": null
    },
    "departure_voyage": {
      "number": null,
      "estimated_time_of_departure": null,
      "vessel": {
        "name": null
      }
    },
    "shipping_line": {
      "code": "MSK",
      "name": "MAERSK LINE",
      "synonyms": [],
      "carrier_type": "ocean",
      "agent": {
        "name": null
      }
    },
    "weight": 0.0,
    "container_vgm": {
      "weight": null,
      "created_at": null,
      "user": {
        "name": null
      }
    },
    "iso_standards_errors": null,
    "current_location_type": "Terminal",
    "current_location": "Terminal: North Terminal",
    "status": "full",
    "usage": "unknown",
    "goods": null,
    "consignees": [],
    "hazmat_codes": [],
    "flex_fields": [
      {
        "label": "Flex Field 1",
        "value": "ABC123"
      },
      {
        "label": "Flex Field 2",
        "value": "XYZ456"
      }
    ],
    "extra_attributes": null,
    "tags": [],
    "over_height": false,
    "over_length": false,
    "over_width": false,
    "is_out_of_gauge": false,
    "actions": {
      "show": {
        "method": "GET",
        "url": "https://app.octopi.co/api/v1/containers/BHCU4942000.json"
      },
      "update": {
        "method": "PATCH",
        "url": "https://app.octopi.co/api/v1/containers/BHCU4942000.json"
      },
      "movements": {
        "method": "GET",
        "url": "https://app.octopi.co/api/v1/containers/BHCU4942000/movements.json"
      }
    }
  }
}

Params

Param name Description
container
required

Validations:

  • Must be a Hash
container[consignee_ids]
optional

an array of consignee ids for this container. Available consignee ids can be retrieved through /api/v1/consignees

Validations:

  • Must be an array of Integer
container[container_type_id]
required

an id of ISO container type. Available container types can be retrieved through /api/v1/container_types

Validations:

  • Must be a number.
container[current_location_id]
required

the container current location id.

Validations:

  • Must be a number.
container[current_location_type]
required

the type of current location

Validations:

  • Must be one of: Container, BerthArea, Other, YardArea, YardSlot, Terminal, Gate, Voyage, Ship, Consignee, Port, TrainVisit.
container[number]
required

the container number

Validations:

  • Must be a String
container[shipping_line_id]
required

the shipping line id of the container

Validations:

  • Must be a number.
container[cargo_type]
optional

The cargo type of the container

Validations:

  • Must be one of: container, vehicle, breakbulk.
container[usage]
optional

Type usage of the container

Validations:

  • Must be one of: unknown, export, import, transshipment_load, restow.
container[status]
optional

the current status of the container

Validations:

  • Must be one of: full, empty.
container[pin]
optional

Container release PIN. If the shipping line is configured to verify this specific PIN, a truck’s entry (Gate In) and interchange departure (Interchange Out) will only be permitted if the value provided in the request matches this one.

Validations:

  • Must be a String
container[hazmat_codes]
optional

hazmat codes on a container using this list of codes.

Validations:

  • Must be an array of String
container[operating_reefer]
optional

indicate if the reefer is in operational status or not (OR or NOR). Note that set_point_temperature cannot be changed on non operational refer and an error will be return in that case.

Validations:

  • Must be one of: true, false, 1, 0.
container[return_temperature]
optional

the current temperature measured by the sensor at the air return of the reefer.

Validations:

  • Must be a decimal number.
container[supply_temperature]
optional

the current temperature inside of the reefer measured by the sensor placed close to the source of cool air.

Validations:

  • Must be a decimal number.
container[set_point_temperature]
optional

the desired temperature that the reefer operator sets for the system to maintain.

Validations:

  • Must be a decimal number.
container[temperature_unit]
optional

The measurement unit for any of temperature params. Accepted values are C, F, celsius, fahrenheit. This params is required if any of temperature params are given.

Validations:

  • Must be one of: C, celsius, F, fahrenheit.
container[reefer_humidity]
optional

the % of humidity inside of the reefer setting.

Validations:

  • Must be a decimal number.
container[reefer_ventilation]
optional

the % of opening the Fresh Air Makeup Vent. The % is used as a setting on that Vent.

Validations:

  • Must be a decimal number.
container[seals]
optional

Seals on a container using this list of seals. A maximum of 4 seals are accepted.

Validations:

  • Must be an array of String
container[over_height]
optional

indicate if the container is over height.

Validations:

  • Must be one of: true, false, 1, 0.
container[over_length]
optional

indicate if the container is over length.

Validations:

  • Must be one of: true, false, 1, 0.
container[over_width]
optional

indicate if the container is over width.

Validations:

  • Must be one of: true, false, 1, 0.
container[flex_fields]
optional

An array of hashes, where each hash contains a flex field’s canonical name and the corresponding value to be set on the container.

Validations:

  • Must be an array of Hash
>>>

PATCH /api/v1/containers/:number.json
Updates the container's attributes.

Supported Formats

json

Errors

Code Description
404 Not Found: one of the requested resources wasn't found.
422 Unprocessable Entity: unable to process request due to an input or validation error.
500 Internal Server Error.

Examples

curl --location --request PATCH 'https://app.octopi.co/api/v1/containers/NUMBER' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=TOKEN' \
--data-raw '{
    "container": {
        "hazmat_codes": ["3536"],
        "current_location_id": 35,
        "current_location_type": "Terminal",
        "flex_fields": [
          { "container_flex_field_1": "ABC123" },
          { "container_flex_field_2": "XYZ456" }
        ]
    }
}'

{
  "container": {
    "container_type_id": 784,
    "hazmat_codes": ["3536"],
    "operating_reefer": true,
    "reefer_humidity": 50.5,
    "reefer_ventilation": 100,
    "return_temperature": 12.0,
    "seals": ["AN22283"],
    "set_point_temperature": 10.0,
    "status": "full",
    "supply_temperature": 11.0,
    "temperature_unit": "C",
    "flex_fields": [
      {
        "label": "Flex Field 1",
        "value": "ABC123"
      },
      {
        "label": "Flex Field 2",
        "value": "XYZ456"
      }
    ]
  }
}

Params

Param name Description
number
required

The number of the container to update

Validations:

  • Must be a String
container
required

Validations:

  • Must be a Hash
container[consignee_ids]
optional

an array of consignee ids for this container. Available consignee ids can be retrieved through /api/v1/consignees

Validations:

  • Must be an array of Integer
container[container_type_id]
optional

an id of ISO container type. Available container types can be retrieved through /api/v1/container_types

Validations:

  • Must be a number.
container[current_location_id]
optional

the container current location id.

Validations:

  • Must be a number.
container[current_location_type]
optional

the type of current location

Validations:

  • Must be one of: Terminal, YardArea, YardSlot, Port, BerthArea.
container[hazmat_codes]
optional

Replace the existing hazmat codes on a container using this list of codes. Passing an empty array removes any hazmat codes from the container.

Validations:

  • Must be an array of String
container[operating_reefer]
optional

indicate if the reefer is in operational status or not (OR or NOR). Note that set_point_temperature cannot be changed on non operational refer and an error will be return in that case.

Validations:

  • Must be one of: true, false, 1, 0.
container[return_temperature]
optional

the current temperature measured by the sensor at the air return of the reefer.

Validations:

  • Must be a decimal number.
container[supply_temperature]
optional

the current temperature inside of the reefer measured by the sensor placed close to the source of cool air.

Validations:

  • Must be a decimal number.
container[set_point_temperature]
optional

the desired temperature that the reefer operator sets for the system to maintain.

Validations:

  • Must be a decimal number.
container[temperature_unit]
optional

the measurement unit for any of temperature params. Accepted values are C, F, celsius, fahrenheit. This params is required if any of temperature params are given.

Validations:

  • Must be one of: C, celsius, F, fahrenheit.
container[reefer_humidity]
optional

the % of humidity inside of the reefer setting.

Validations:

  • Must be a decimal number.
container[reefer_ventilation]
optional

the % of opening the Fresh Air Makeup Vent. The % is used as a setting on that Vent.

Validations:

  • Must be a decimal number.
container[seals]
optional

Replace the existing seals on a container using this list of seals. A maximum of 4 seals are accepted. Passing an empty array removes any seals from the container.

Validations:

  • Must be an array of String
container[status]
optional

the current status of the container

Validations:

  • Must be one of: full, empty.
container[over_height]
optional

indicate if the container is over height.

Validations:

  • Must be one of: true, false, 1, 0.
container[over_length]
optional

indicate if the container is over length.

Validations:

  • Must be one of: true, false, 1, 0.
container[over_width]
optional

indicate if the container is over width.

Validations:

  • Must be one of: true, false, 1, 0.
container[flex_fields]
optional

An array of hashes, where each hash contains a flex field’s canonical name and the corresponding value to be set on the container.

Validations:

  • Must be an array of Hash