> For the complete documentation index, see [llms.txt](https://cargospot.gitbook.io/cargospot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cargospot.gitbook.io/cargospot/models.md).

# Models

## The TokenRequest object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"TokenRequest":{"type":"object","required":["access_key_id","access_key_secret","grant_type"],"properties":{"access_key_id":{"type":"string"},"access_key_secret":{"type":"string"},"grant_type":{"type":"string"}}}}}}
```

## The TokenResponse object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"TokenResponse":{"type":"object","required":["access_token","token_type"],"properties":{"access_token":{"type":"string","description":"JWT access token"},"token_type":{"type":"string"},"expires_in":{"type":"integer","description":"Token lifetime in seconds"},"scope":{"type":"string","description":"Optional scope string returned by the auth server"}}}}}}
```

## The ShipmentCreateRequest object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"ShipmentCreateRequest":{"$ref":"#/components/schemas/ShipmentPayload"},"ShipmentPayload":{"type":"object","required":["basicDetails"],"properties":{"basicDetails":{"$ref":"#/components/schemas/BasicDetails"},"itemDetails":{"type":"array","items":{"$ref":"#/components/schemas/ItemDetail"}},"stops":{"type":"array","items":{"$ref":"#/components/schemas/Stop"}},"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}},"BasicDetails":{"type":"object","properties":{"shipmentNo":{"type":"string"},"bolNumber":{"type":"string"},"instruction":{"type":"string"},"proNumber":{"type":"string"},"tmsRefNo":{"type":"string"},"shipmentStatus":{"type":"string"},"shipmentMode":{"type":"string"},"pickupDate":{"type":"string","format":"date"},"pickupStartTime":{"type":"string","format":"date-time"},"pickupEndTime":{"type":"string","format":"date-time"},"deliveryDate":{"type":"string","format":"date"},"deliveryStartTime":{"type":"string","format":"date-time"},"deliveryEndTime":{"type":"string","format":"date-time"},"billTo":{"$ref":"#/components/schemas/BillTo"},"refNums":{"type":"array","items":{"$ref":"#/components/schemas/RefNum"}}}},"BillTo":{"type":"object","properties":{"companyName":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"}}},"RefNum":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}},"ItemDetail":{"type":"object","properties":{"itemName":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"integer","format":"int32"},"itemUnit":{"type":"string"},"freightClass":{"type":"string"},"nmfcNumber":{"type":"string"},"totalWeight":{"type":"number","format":"double"},"weightUnit":{"type":"string"},"length":{"type":"number","format":"double"},"width":{"type":"number","format":"double"},"height":{"type":"number","format":"double"},"dimensionUnit":{"type":"string"},"isHazmat":{"type":"boolean"},"isStackable":{"type":"boolean"},"isPerishable":{"type":"boolean"},"minimumTemperature":{"type":"number","format":"double"},"maximumTemperature":{"type":"number","format":"double"},"temperatureUnit":{"type":"string"}}},"Stop":{"type":"object","properties":{"sequence":{"type":"integer","format":"int32"},"stopName":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"actionType":{"type":"string"},"message":{"type":"string"},"latitude":{"type":"string"},"longitude":{"type":"string"},"timeZone":{"type":"string"},"accessorial":{"type":"array","items":{"$ref":"#/components/schemas/Accessorial"}},"contact":{"type":"array","items":{"$ref":"#/components/schemas/StopContact"}}}},"Accessorial":{"type":"object","properties":{"accessorialName":{"type":"string"},"stopActionType":{"type":"string"}}},"StopContact":{"type":"object","properties":{"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"},"contactType":{"type":"string"}}},"Note":{"type":"object","properties":{"note":{"type":"string"}}}}}}
```

## The ShipmentUpdateRequest object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"ShipmentUpdateRequest":{"$ref":"#/components/schemas/ShipmentPayload"},"ShipmentPayload":{"type":"object","required":["basicDetails"],"properties":{"basicDetails":{"$ref":"#/components/schemas/BasicDetails"},"itemDetails":{"type":"array","items":{"$ref":"#/components/schemas/ItemDetail"}},"stops":{"type":"array","items":{"$ref":"#/components/schemas/Stop"}},"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}},"BasicDetails":{"type":"object","properties":{"shipmentNo":{"type":"string"},"bolNumber":{"type":"string"},"instruction":{"type":"string"},"proNumber":{"type":"string"},"tmsRefNo":{"type":"string"},"shipmentStatus":{"type":"string"},"shipmentMode":{"type":"string"},"pickupDate":{"type":"string","format":"date"},"pickupStartTime":{"type":"string","format":"date-time"},"pickupEndTime":{"type":"string","format":"date-time"},"deliveryDate":{"type":"string","format":"date"},"deliveryStartTime":{"type":"string","format":"date-time"},"deliveryEndTime":{"type":"string","format":"date-time"},"billTo":{"$ref":"#/components/schemas/BillTo"},"refNums":{"type":"array","items":{"$ref":"#/components/schemas/RefNum"}}}},"BillTo":{"type":"object","properties":{"companyName":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"}}},"RefNum":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}},"ItemDetail":{"type":"object","properties":{"itemName":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"integer","format":"int32"},"itemUnit":{"type":"string"},"freightClass":{"type":"string"},"nmfcNumber":{"type":"string"},"totalWeight":{"type":"number","format":"double"},"weightUnit":{"type":"string"},"length":{"type":"number","format":"double"},"width":{"type":"number","format":"double"},"height":{"type":"number","format":"double"},"dimensionUnit":{"type":"string"},"isHazmat":{"type":"boolean"},"isStackable":{"type":"boolean"},"isPerishable":{"type":"boolean"},"minimumTemperature":{"type":"number","format":"double"},"maximumTemperature":{"type":"number","format":"double"},"temperatureUnit":{"type":"string"}}},"Stop":{"type":"object","properties":{"sequence":{"type":"integer","format":"int32"},"stopName":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"actionType":{"type":"string"},"message":{"type":"string"},"latitude":{"type":"string"},"longitude":{"type":"string"},"timeZone":{"type":"string"},"accessorial":{"type":"array","items":{"$ref":"#/components/schemas/Accessorial"}},"contact":{"type":"array","items":{"$ref":"#/components/schemas/StopContact"}}}},"Accessorial":{"type":"object","properties":{"accessorialName":{"type":"string"},"stopActionType":{"type":"string"}}},"StopContact":{"type":"object","properties":{"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"},"contactType":{"type":"string"}}},"Note":{"type":"object","properties":{"note":{"type":"string"}}}}}}
```

## The ShipmentCreateResponse object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"ShipmentCreateResponse":{"type":"object","required":["uniqueId"],"properties":{"uniqueId":{"type":"string"}}}}}}
```

## The ShipmentGetResponse object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"ShipmentGetResponse":{"allOf":[{"type":"object","required":["uniqueId"],"properties":{"uniqueId":{"type":"string"}}},{"$ref":"#/components/schemas/ShipmentPayload"}]},"ShipmentPayload":{"type":"object","required":["basicDetails"],"properties":{"basicDetails":{"$ref":"#/components/schemas/BasicDetails"},"itemDetails":{"type":"array","items":{"$ref":"#/components/schemas/ItemDetail"}},"stops":{"type":"array","items":{"$ref":"#/components/schemas/Stop"}},"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}},"BasicDetails":{"type":"object","properties":{"shipmentNo":{"type":"string"},"bolNumber":{"type":"string"},"instruction":{"type":"string"},"proNumber":{"type":"string"},"tmsRefNo":{"type":"string"},"shipmentStatus":{"type":"string"},"shipmentMode":{"type":"string"},"pickupDate":{"type":"string","format":"date"},"pickupStartTime":{"type":"string","format":"date-time"},"pickupEndTime":{"type":"string","format":"date-time"},"deliveryDate":{"type":"string","format":"date"},"deliveryStartTime":{"type":"string","format":"date-time"},"deliveryEndTime":{"type":"string","format":"date-time"},"billTo":{"$ref":"#/components/schemas/BillTo"},"refNums":{"type":"array","items":{"$ref":"#/components/schemas/RefNum"}}}},"BillTo":{"type":"object","properties":{"companyName":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"}}},"RefNum":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}},"ItemDetail":{"type":"object","properties":{"itemName":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"integer","format":"int32"},"itemUnit":{"type":"string"},"freightClass":{"type":"string"},"nmfcNumber":{"type":"string"},"totalWeight":{"type":"number","format":"double"},"weightUnit":{"type":"string"},"length":{"type":"number","format":"double"},"width":{"type":"number","format":"double"},"height":{"type":"number","format":"double"},"dimensionUnit":{"type":"string"},"isHazmat":{"type":"boolean"},"isStackable":{"type":"boolean"},"isPerishable":{"type":"boolean"},"minimumTemperature":{"type":"number","format":"double"},"maximumTemperature":{"type":"number","format":"double"},"temperatureUnit":{"type":"string"}}},"Stop":{"type":"object","properties":{"sequence":{"type":"integer","format":"int32"},"stopName":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"actionType":{"type":"string"},"message":{"type":"string"},"latitude":{"type":"string"},"longitude":{"type":"string"},"timeZone":{"type":"string"},"accessorial":{"type":"array","items":{"$ref":"#/components/schemas/Accessorial"}},"contact":{"type":"array","items":{"$ref":"#/components/schemas/StopContact"}}}},"Accessorial":{"type":"object","properties":{"accessorialName":{"type":"string"},"stopActionType":{"type":"string"}}},"StopContact":{"type":"object","properties":{"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"},"contactType":{"type":"string"}}},"Note":{"type":"object","properties":{"note":{"type":"string"}}}}}}
```

## The ShipmentPayload object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"ShipmentPayload":{"type":"object","required":["basicDetails"],"properties":{"basicDetails":{"$ref":"#/components/schemas/BasicDetails"},"itemDetails":{"type":"array","items":{"$ref":"#/components/schemas/ItemDetail"}},"stops":{"type":"array","items":{"$ref":"#/components/schemas/Stop"}},"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}},"BasicDetails":{"type":"object","properties":{"shipmentNo":{"type":"string"},"bolNumber":{"type":"string"},"instruction":{"type":"string"},"proNumber":{"type":"string"},"tmsRefNo":{"type":"string"},"shipmentStatus":{"type":"string"},"shipmentMode":{"type":"string"},"pickupDate":{"type":"string","format":"date"},"pickupStartTime":{"type":"string","format":"date-time"},"pickupEndTime":{"type":"string","format":"date-time"},"deliveryDate":{"type":"string","format":"date"},"deliveryStartTime":{"type":"string","format":"date-time"},"deliveryEndTime":{"type":"string","format":"date-time"},"billTo":{"$ref":"#/components/schemas/BillTo"},"refNums":{"type":"array","items":{"$ref":"#/components/schemas/RefNum"}}}},"BillTo":{"type":"object","properties":{"companyName":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"}}},"RefNum":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}},"ItemDetail":{"type":"object","properties":{"itemName":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"integer","format":"int32"},"itemUnit":{"type":"string"},"freightClass":{"type":"string"},"nmfcNumber":{"type":"string"},"totalWeight":{"type":"number","format":"double"},"weightUnit":{"type":"string"},"length":{"type":"number","format":"double"},"width":{"type":"number","format":"double"},"height":{"type":"number","format":"double"},"dimensionUnit":{"type":"string"},"isHazmat":{"type":"boolean"},"isStackable":{"type":"boolean"},"isPerishable":{"type":"boolean"},"minimumTemperature":{"type":"number","format":"double"},"maximumTemperature":{"type":"number","format":"double"},"temperatureUnit":{"type":"string"}}},"Stop":{"type":"object","properties":{"sequence":{"type":"integer","format":"int32"},"stopName":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"actionType":{"type":"string"},"message":{"type":"string"},"latitude":{"type":"string"},"longitude":{"type":"string"},"timeZone":{"type":"string"},"accessorial":{"type":"array","items":{"$ref":"#/components/schemas/Accessorial"}},"contact":{"type":"array","items":{"$ref":"#/components/schemas/StopContact"}}}},"Accessorial":{"type":"object","properties":{"accessorialName":{"type":"string"},"stopActionType":{"type":"string"}}},"StopContact":{"type":"object","properties":{"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"},"contactType":{"type":"string"}}},"Note":{"type":"object","properties":{"note":{"type":"string"}}}}}}
```

## The BasicDetails object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"BasicDetails":{"type":"object","properties":{"shipmentNo":{"type":"string"},"bolNumber":{"type":"string"},"instruction":{"type":"string"},"proNumber":{"type":"string"},"tmsRefNo":{"type":"string"},"shipmentStatus":{"type":"string"},"shipmentMode":{"type":"string"},"pickupDate":{"type":"string","format":"date"},"pickupStartTime":{"type":"string","format":"date-time"},"pickupEndTime":{"type":"string","format":"date-time"},"deliveryDate":{"type":"string","format":"date"},"deliveryStartTime":{"type":"string","format":"date-time"},"deliveryEndTime":{"type":"string","format":"date-time"},"billTo":{"$ref":"#/components/schemas/BillTo"},"refNums":{"type":"array","items":{"$ref":"#/components/schemas/RefNum"}}}},"BillTo":{"type":"object","properties":{"companyName":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"}}},"RefNum":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}}}}}
```

## The BillTo object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"BillTo":{"type":"object","properties":{"companyName":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"}}}}}}
```

## The RefNum object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"RefNum":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}}}}}
```

## The ItemDetail object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"ItemDetail":{"type":"object","properties":{"itemName":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"integer","format":"int32"},"itemUnit":{"type":"string"},"freightClass":{"type":"string"},"nmfcNumber":{"type":"string"},"totalWeight":{"type":"number","format":"double"},"weightUnit":{"type":"string"},"length":{"type":"number","format":"double"},"width":{"type":"number","format":"double"},"height":{"type":"number","format":"double"},"dimensionUnit":{"type":"string"},"isHazmat":{"type":"boolean"},"isStackable":{"type":"boolean"},"isPerishable":{"type":"boolean"},"minimumTemperature":{"type":"number","format":"double"},"maximumTemperature":{"type":"number","format":"double"},"temperatureUnit":{"type":"string"}}}}}}
```

## The Stop object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"Stop":{"type":"object","properties":{"sequence":{"type":"integer","format":"int32"},"stopName":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"actionType":{"type":"string"},"message":{"type":"string"},"latitude":{"type":"string"},"longitude":{"type":"string"},"timeZone":{"type":"string"},"accessorial":{"type":"array","items":{"$ref":"#/components/schemas/Accessorial"}},"contact":{"type":"array","items":{"$ref":"#/components/schemas/StopContact"}}}},"Accessorial":{"type":"object","properties":{"accessorialName":{"type":"string"},"stopActionType":{"type":"string"}}},"StopContact":{"type":"object","properties":{"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"},"contactType":{"type":"string"}}}}}}
```

## The Accessorial object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"Accessorial":{"type":"object","properties":{"accessorialName":{"type":"string"},"stopActionType":{"type":"string"}}}}}}
```

## The StopContact object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"StopContact":{"type":"object","properties":{"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"phonePrefix":{"type":"string"},"contactType":{"type":"string"}}}}}}
```

## The Note object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"Note":{"type":"object","properties":{"note":{"type":"string"}}}}}}
```

## The ShipmentFilterDTO object

```json
{"openapi":"3.0.3","info":{"title":"CargoSpot Shipments API","version":"1.0.0"},"components":{"schemas":{"ShipmentFilterDTO":{"type":"object","properties":{"shipmentNo":{"type":"string"},"bolNumber":{"type":"string","description":"Filter by BOL number (partial match)."},"proNumber":{"type":"string","description":"Filter by PRO number (partial match)."},"referenceNumber":{"type":"string","description":"Filter by any reference number on the shipment (partial match)."},"uniqueId":{"type":"string"},"status":{"type":"array","items":{"type":"string"}},"deliveryEndDate":{"type":"string","format":"date"},"deliveryStartDate":{"type":"string","format":"date"},"pickupEndDate":{"type":"string","format":"date"},"pickupStartDate":{"type":"string","format":"date"},"trackerTypes":{"type":"array","items":{"type":"string"}},"shipmentModeCd":{"type":"integer","format":"int64"},"isFlagged":{"type":"boolean"},"actionRequired":{"type":"boolean"},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"sortColumn":{"type":"string"},"sortOrder":{"type":"string"},"shipmentMode":{"type":"array","items":{"type":"string"}},"carrierOrgIds":{"type":"array","items":{"type":"integer","format":"int64"}},"driverIds":{"type":"array","items":{"type":"integer","format":"int64"}},"sourceLocationIds":{"type":"array","items":{"type":"string","format":"uuid"}},"destinationLocationIds":{"type":"array","items":{"type":"string","format":"uuid"}},"customerIds":{"type":"array","items":{"type":"string","format":"uuid"}},"vehicleIds":{"type":"array","items":{"type":"string","format":"uuid"}},"itemIds":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cargospot.gitbook.io/cargospot/models.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.