API documentation

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/: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

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

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

Supported Formats

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

Supported Formats

Errors

Examples

Params

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

Supported Formats

Errors

Examples

Params

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

Supported Formats

Errors

Examples

Params

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

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

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

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