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. It also returns information about the last movement that was recorded for this container.

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_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"
        }
      ]
    }
  }
}

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