---
updatedAt: 2026-06-02T13:36:45.000Z
agentTools:
  projectIndex: https://developers.forto.com/llms.txt
---

# List/Filter/Paginate Shipments

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "paths": {
    "/v1/shipments": {
      "get": {
        "operationId": "getShipmentsv1",
        "parameters": [
          {
            "name": "_id",
            "required": false,
            "in": "query",
            "description": "ID of the shipment",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "customerReference",
            "required": false,
            "in": "query",
            "description": "Customer Reference of the shipment. Query is case insensitive and partial matches are supported.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "states",
            "required": false,
            "in": "query",
            "description": "Shipment States",
            "schema": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "new",
                  "active",
                  "completed",
                  "canceled",
                  "closed"
                ]
              }
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Desired amount of entities in the response",
            "schema": {
              "minimum": 1,
              "maximum": 50,
              "default": 50,
              "type": "number"
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Desired page of entities",
            "schema": {
              "minimum": 1,
              "default": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated response of Shipments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListShipmentsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Request is malformed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIValidationError"
                }
              }
            }
          },
          "401": {
            "description": "Authorization failed for this request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIAuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIAuthorizationError"
                }
              }
            }
          },
          "404": {
            "description": "Requested resource cannot be found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APINotFoundError"
                }
              }
            }
          },
          "default": {
            "description": "Default Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          }
        },
        "security": [
          {
            "Authorization": []
          }
        ],
        "summary": "List/Filter/Paginate Shipments",
        "tags": [
          "Shipment"
        ]
      }
    }
  },
  "info": {
    "title": "Forto Platform API",
    "description": "Public API schema",
    "version": "1.0",
    "contact": {
      "name": "Customer Integrations Team",
      "url": "",
      "email": ""
    }
  },
  "servers": [
    {
      "url": "https://public-api.forto.io",
      "description": "Our Sandbox API"
    },
    {
      "url": "https://public-api.forto.com",
      "description": "Our Production API"
    }
  ],
  "components": {
    "securitySchemes": {
      "Authorization": {
        "scheme": "bearer",
        "bearerFormat": "Forto API Key Format",
        "type": "http",
        "description": "API Key"
      }
    },
    "schemas": {
      "ErrorDetails": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field causing the issue"
          },
          "value": {
            "type": "object",
            "description": "Value of the field causing the issue"
          },
          "location": {
            "type": "string",
            "description": "Location of the field causing the issue",
            "enum": [
              "path",
              "body",
              "query"
            ]
          },
          "issue": {
            "type": "string",
            "description": "The reason for the error"
          }
        },
        "required": [
          "field",
          "issue"
        ]
      },
      "APIValidationError": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "default": "ValidationException",
            "description": "Name of ValidationException",
            "enum": [
              "ValidationException"
            ]
          },
          "debugID": {
            "type": "string",
            "description": "Internal identifier used for correlation purposes."
          },
          "message": {
            "type": "string",
            "description": "Message describing the error."
          },
          "informationLink": {
            "type": "string",
            "description": "URI for detailed information related to this error for the developer."
          },
          "details": {
            "description": "Additional details for the error. ",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorDetails"
            }
          }
        },
        "required": [
          "name",
          "debugID",
          "message",
          "details"
        ]
      },
      "APIAuthenticationError": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "default": "AuthenticationException",
            "description": "Name of AuthenticationException",
            "enum": [
              "AuthenticationException"
            ]
          },
          "debugID": {
            "type": "string",
            "description": "Internal identifier used for correlation purposes."
          },
          "message": {
            "type": "string",
            "description": "Message describing the error."
          },
          "informationLink": {
            "type": "string",
            "description": "URI for detailed information related to this error for the developer."
          },
          "details": {
            "description": "Additional details for the error. ",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorDetails"
            }
          }
        },
        "required": [
          "name",
          "debugID",
          "message"
        ]
      },
      "APIAuthorizationError": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "default": "AuthorizationException",
            "description": "Name of AuthorizationException",
            "enum": [
              "AuthorizationException"
            ]
          },
          "debugID": {
            "type": "string",
            "description": "Internal identifier used for correlation purposes."
          },
          "message": {
            "type": "string",
            "description": "Message describing the error."
          },
          "informationLink": {
            "type": "string",
            "description": "URI for detailed information related to this error for the developer."
          },
          "details": {
            "description": "Additional details for the error. ",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorDetails"
            }
          }
        },
        "required": [
          "name",
          "debugID",
          "message"
        ]
      },
      "APINotFoundError": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "default": "NotFoundException",
            "description": "Name of NotFoundException",
            "enum": [
              "NotFoundException"
            ]
          },
          "debugID": {
            "type": "string",
            "description": "Internal identifier used for correlation purposes."
          },
          "message": {
            "type": "string",
            "description": "Message describing the error."
          },
          "informationLink": {
            "type": "string",
            "description": "URI for detailed information related to this error for the developer."
          },
          "details": {
            "description": "Additional details for the error. ",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorDetails"
            }
          }
        },
        "required": [
          "name",
          "debugID",
          "message"
        ]
      },
      "APIError": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Human readable, unique name of the error."
          },
          "debugID": {
            "type": "string",
            "description": "Internal identifier used for correlation purposes."
          },
          "message": {
            "type": "string",
            "description": "Message describing the error."
          },
          "informationLink": {
            "type": "string",
            "description": "URI for detailed information related to this error for the developer."
          },
          "details": {
            "description": "Additional details for the error. ",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorDetails"
            }
          }
        },
        "required": [
          "name",
          "debugID",
          "message"
        ]
      },
      "Carrier": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of the carrier"
          },
          "name": {
            "type": "string",
            "description": "Name of the carrier"
          },
          "flightNumber": {
            "type": "string",
            "nullable": true,
            "description": "Flight number"
          },
          "airline": {
            "type": "string",
            "nullable": true,
            "description": "Airline"
          },
          "airlineCode": {
            "type": "string",
            "nullable": true,
            "description": "Airline Code"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "ShipmentHblNumber": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type of HBL",
            "nullable": true
          },
          "number": {
            "type": "string",
            "description": "Number of HBL"
          }
        },
        "required": [
          "number"
        ]
      },
      "Emissions": {
        "type": "object",
        "properties": {
          "preCarriage": {
            "type": "number",
            "description": "Pre-carriage emissions (CO2e)"
          },
          "mainCarriage": {
            "type": "number",
            "description": "Main carriage emissions (CO2e)"
          },
          "onCarriage": {
            "type": "number",
            "description": "On-carriage emissions (CO2e)"
          }
        },
        "required": [
          "preCarriage",
          "mainCarriage",
          "onCarriage"
        ]
      },
      "ContainerCustomerData": {
        "type": "object",
        "properties": {
          "earliestETW": {
            "type": "string",
            "description": "Earliest ETW",
            "format": "date-time"
          },
          "latestETW": {
            "type": "string",
            "description": "Latest ETW",
            "format": "date-time"
          }
        }
      },
      "CustomerTag": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "value"
        ]
      },
      "ShipmentContainer": {
        "type": "object",
        "properties": {
          "size": {
            "type": "string",
            "description": "Size of the container",
            "enum": [
              "22GP",
              "42GP",
              "45GP",
              null
            ]
          },
          "_id": {
            "type": "string",
            "description": "ID of the container"
          },
          "containerNumber": {
            "type": "string",
            "description": "Physical container number"
          },
          "customerReference": {
            "type": "string",
            "nullable": true,
            "description": "Reference for the customer"
          },
          "customsReferenceNumber": {
            "description": "Customs reference numbers",
            "items": {
              "type": "array"
            },
            "type": "array"
          },
          "customerData": {
            "description": "Customer Data",
            "allOf": [
              {
                "$ref": "#/components/schemas/ContainerCustomerData"
              }
            ]
          },
          "tags": {
            "description": "User-defined array of tags, in key-value format",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomerTag"
            }
          }
        },
        "required": [
          "_id",
          "customerReference",
          "customsReferenceNumber"
        ]
      },
      "ShipmentCargo": {
        "type": "object",
        "properties": {
          "quantity": {
            "type": "number",
            "nullable": true,
            "minimum": 1,
            "description": "Quantity"
          },
          "height": {
            "type": "number",
            "nullable": true,
            "description": "Height (m)"
          },
          "length": {
            "type": "number",
            "nullable": true,
            "description": "Length (m)"
          },
          "width": {
            "type": "number",
            "nullable": true,
            "description": "Width (m)"
          },
          "volume": {
            "type": "number",
            "nullable": true,
            "description": "Volume (m3)"
          },
          "totalVolume": {
            "type": "number",
            "nullable": true,
            "description": "Total Volume (m3) - Volume * Quantity"
          },
          "unitWeight": {
            "type": "number",
            "nullable": true,
            "description": "Unit Weight (kg)"
          },
          "totalWeight": {
            "type": "number",
            "nullable": true,
            "description": "Total Weight (kg) - Unit Weight * Quantity"
          },
          "commodityType": {
            "type": "string",
            "description": "Commodity Type"
          }
        },
        "required": [
          "quantity",
          "height",
          "length",
          "width",
          "volume",
          "totalVolume",
          "unitWeight",
          "totalWeight"
        ]
      },
      "Shipment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of the shipment"
          },
          "customerReference": {
            "type": "string",
            "nullable": true,
            "description": "Reference given to the shipment by the customer"
          },
          "shipName": {
            "type": "string",
            "nullable": true,
            "description": "Vessel name for the shipment"
          },
          "shipperName": {
            "type": "string",
            "nullable": true,
            "description": "Name of the shipper of the shipment"
          },
          "consigneeName": {
            "type": "string",
            "nullable": true,
            "description": "Name of the consignee of the shipment"
          },
          "state": {
            "type": "string",
            "description": "State that the shipment is in",
            "enum": [
              "new",
              "active",
              "completed",
              "canceled",
              "closed"
            ]
          },
          "transportType": {
            "type": "string",
            "description": "Type of the transport",
            "enum": [
              "fcl",
              "lcl"
            ]
          },
          "transportMode": {
            "type": "string",
            "description": "Mode of the transport",
            "enum": [
              "sea",
              "air",
              "seaAir",
              "rail"
            ]
          },
          "portOfLoading": {
            "type": "string",
            "description": "Code for port of loading"
          },
          "portOfDischarge": {
            "type": "string",
            "description": "Code for port of discharge"
          },
          "cargoReadyDate": {
            "type": "string",
            "nullable": true,
            "description": "Cargo ready date",
            "format": "date-time"
          },
          "estimatedDepartureDate": {
            "type": "string",
            "nullable": true,
            "description": "Estimated date for departure",
            "format": "date-time"
          },
          "estimatedArrivalDate": {
            "type": "string",
            "nullable": true,
            "description": "Estimated date for arrival",
            "format": "date-time"
          },
          "incoTerm": {
            "type": "string",
            "description": "Incoterm",
            "enum": [
              "EXW",
              "FCA_LW",
              "FCA_T",
              "FAS",
              "FOB",
              "CFR",
              "CIF",
              "CPT",
              "CIP",
              "DPU",
              "DAP",
              "DDP"
            ]
          },
          "carrier": {
            "description": "Carrier assigned to the shipment",
            "allOf": [
              {
                "$ref": "#/components/schemas/Carrier"
              }
            ]
          },
          "onCarriageTransportMode": {
            "type": "string",
            "nullable": true,
            "description": "On Carriage transport mode",
            "enum": [
              "truck",
              "barge",
              "rail"
            ]
          },
          "bookingNumber": {
            "type": "string",
            "nullable": true,
            "description": "Booking number"
          },
          "hblNumber": {
            "type": "string",
            "nullable": true,
            "description": "HBL number. DEPRECATED. This field will be removed in a future version. Please use hblList instead.",
            "deprecated": true
          },
          "hblList": {
            "description": "HBL numbers",
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/ShipmentHblNumber"
              }
            ]
          },
          "mblNumber": {
            "type": "string",
            "nullable": true,
            "description": "MBL number"
          },
          "mawbNumber": {
            "type": "string",
            "nullable": true,
            "description": "MAWB number. Available if transport mode is AIR."
          },
          "hawbNumber": {
            "type": "string",
            "nullable": true,
            "description": "HAWB number. Available if transport mode is AIR."
          },
          "emissions": {
            "nullable": true,
            "description": "Emissions of the shipment (KgCO2e)",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Emissions"
            }
          },
          "containers": {
            "nullable": true,
            "description": "Containers of the shipment. Null if its an LCL shipment",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentContainer"
            }
          },
          "cargo": {
            "nullable": true,
            "description": "Cargo of the shipment. Exists if its an LCL shipment",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentCargo"
            }
          },
          "tags": {
            "description": "User-defined array of tags, in key-value format",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomerTag"
            }
          }
        },
        "required": [
          "id",
          "customerReference",
          "shipName",
          "shipperName",
          "consigneeName",
          "state",
          "transportType",
          "transportMode",
          "portOfLoading",
          "portOfDischarge",
          "cargoReadyDate",
          "estimatedDepartureDate",
          "estimatedArrivalDate",
          "incoTerm",
          "carrier",
          "onCarriageTransportMode",
          "bookingNumber",
          "hblNumber",
          "mblNumber",
          "mawbNumber",
          "hawbNumber",
          "emissions",
          "containers",
          "cargo"
        ]
      },
      "ListShipmentsResponse": {
        "type": "object",
        "properties": {
          "items": {
            "description": "Shipments",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shipment"
            }
          },
          "total": {
            "type": "number",
            "minimum": 0,
            "description": "Total number of items found. DEPRECATED. This field will be removed in a future version. Please use totalItems instead.",
            "deprecated": true
          },
          "totalItems": {
            "type": "number",
            "minimum": 0,
            "description": "Total number of items found"
          },
          "page": {
            "type": "number",
            "minimum": 1,
            "description": "Current page number"
          },
          "pageSize": {
            "type": "number",
            "minimum": 1,
            "description": "Requested size of the page"
          }
        },
        "required": [
          "items",
          "total",
          "totalItems",
          "page",
          "pageSize"
        ]
      }
    }
  }
}
```