{ "openapi": "3.0.3", "info": { "title": "Cargobase Pluto API", "version": "1.0.0", "description": "The main **public partner API** for integrating with Cargobase over `/api/1`.\n\nCreate and manage freight in Production (https://pluto.cargobase.com) or Sandbox—quick requests, quotes, shipments, invoices, and tracking. Authenticate with a shipper or provider token.\n\n## What’s in this API\n\nUse the sidebar sections below. In general:\n\n| Section | What it’s for |\n| --- | --- |\n| **Quick Requests** | Create and list lightweight shipping orders (quick requests) without a full quote workflow. |\n| **System Drafts** | Build and edit v4-style quote-request drafts (addresses, stops, cargo) before converting them into a live request. |\n| **Quote Requests** | Create quote requests, review active/archived requests, and follow award / provider responses. |\n| **Shipments** | Look up active shipments and shipment detail once freight is moving. |\n| **Invoices** | List invoices for a time range and open individual invoice detail. |\n| **Tracking** | Push tracking updates into Cargobase (e.g. generic tracking posts from providers). |\n| **Models** | Shared request/response schemas referenced by the endpoints above. |" }, "servers": [ { "url": "https://pluto.cargobase.com", "description": "Production" }, { "url": "https://sandbox.cargobase.com", "description": "Sandbox" } ], "components": { "securitySchemes": { "TokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Token-based authentication (Django REST framework style).\n\nFormat: `Token `\n\nExample: `Token your_token_here`" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer token authentication (alternate).\n\nFormat: `Bearer `\n\nExample: `Bearer your_token_here`" } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Standard error envelope", "properties": { "detail": { "type": "string", "description": "Human-readable error message" }, "message": { "type": "string" } }, "additionalProperties": true }, "ValidationErrorBody": { "type": "object", "description": "Field-level validation errors. Structure follows Django REST Framework\nnested error maps: keys are field names (or `non_field_errors`),\nvalues are string arrays or nested objects.\n", "additionalProperties": true, "example": { "organizational": { "location": [ "This field is required for convert." ] }, "packing_list": [ { "handling_unit": [ "Invalid handling unit." ] } ] } }, "PaginatedAddressList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "description": "Total number of matching addresses", "example": 12 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AddressObject" } } } }, "PaginatedDraftList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "description": "Total number of matching drafts", "example": 3 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DraftSummary" } } } }, "AddressObject": { "type": "object", "description": "Address v2 record returned by list addresses", "properties": { "reference_number": { "type": "string", "description": "Unique address reference. Use as stop `address_reference_number`.", "example": "A12345678" }, "location_reference_number": { "type": "string", "nullable": true, "description": "ERP location reference. Use as stop `location_reference_number`.", "example": "ERP-WH-01" }, "name": { "type": "string", "nullable": true }, "street": { "type": "string", "nullable": true }, "street_line2": { "type": "string", "nullable": true }, "zipcode": { "type": "string", "nullable": true }, "city_name": { "type": "string", "nullable": true }, "state_name": { "type": "string", "nullable": true }, "country_name": { "type": "string", "nullable": true }, "contact_name": { "type": "string", "nullable": true }, "contact_number": { "type": "string", "nullable": true }, "contact_email": { "type": "string", "nullable": true, "format": "email" } } }, "DraftSummary": { "type": "object", "description": "Lightweight draft summary row", "properties": { "draft_reference_number": { "type": "string", "example": "D12345678" }, "external_id": { "type": "string", "nullable": true, "example": "ERP_ID_1710000000" }, "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "title": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true, "description": "Payment location (`cb_account_number`)" }, "has_validation_errors": { "type": "boolean" } } }, "AttachmentRef": { "type": "object", "description": "Stored `other_attachments` item. Prefer uploading via POST .../attachments/ (multipart); create/PATCH may still accept these refs when you already have a FileUpload.", "properties": { "id": { "type": "integer", "description": "FileUpload database id" }, "name": { "type": "string", "example": "extra.pdf" }, "reference_number": { "type": "string", "description": "FileUpload reference (`FU…`)", "example": "FU12345678" }, "file_extension": { "type": "string", "example": "pdf" }, "url": { "type": "string", "format": "uri" } }, "required": [ "reference_number" ], "additionalProperties": true }, "BucketAttachment": { "type": "object", "description": "Named bucket attachment ref on a draft (`bucket_attachments`).", "properties": { "id": { "type": "integer" }, "file": { "type": "string", "description": "FileUpload reference (`FU…`)", "example": "FU84121391" }, "filename": { "type": "string", "example": "certificate.pdf" }, "url": { "type": "string", "format": "uri" }, "bucket_name": { "type": "string", "example": "CERTIFICATE_OF_ORIGIN" } }, "additionalProperties": true }, "GoodCustomsInformation": { "type": "object", "description": "Commercial / customs details for one product inside a handling unit", "properties": { "value": { "type": "number", "nullable": true, "description": "Monetary value of the product in this handling unit", "example": 8000 }, "currency_code": { "type": "string", "nullable": true, "description": "3-letter ISO 4217 currency code", "example": "USD" }, "description": { "type": "string", "nullable": true, "example": "Spare parts" }, "hs_code": { "type": "string", "nullable": true, "description": "Harmonized System code", "example": "8483.40" } }, "additionalProperties": true }, "PackingListItem": { "type": "object", "description": "A single packing-list / cargo line.\n\nStandard `handling_unit` values: `bag`, `box`, `carton`, `case`,\n`crate`, `container`, `pallet`, `tube`. Company custom units are also\naccepted.\n\nWhen `handling_unit` is `container`, set `handling_unit_value` to\n`LCL` or `FCL` and send `container_type` (integer-as-string).\n\nIf `temperature_control_value` is `6` (Other), also set\n`temperature_controlled_custom_value`.\n", "properties": { "line_key": { "type": "string", "nullable": true, "description": "Caller or server line identifier" }, "pickup_stop_key": { "type": "string", "nullable": true, "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.", "example": "pickup-1" }, "delivery_stop_key": { "type": "string", "nullable": true, "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.", "example": "delivery-1" }, "good_item_id": { "type": "integer", "nullable": true }, "handling_unit": { "type": "string", "nullable": true, "description": "Handling unit type. Standard values:\n\n`bag`, `box`, `carton`, `case`, `crate`, `container`, `pallet`, `tube`\n\nCompany-configured custom units are also accepted.\n", "example": "pallet" }, "handling_unit_value": { "type": "string", "nullable": true, "description": "For `handling_unit=container`, use `LCL` or `FCL`.\nOtherwise free text or `null`.\n", "example": "FCL" }, "units": { "type": "integer", "nullable": true, "description": "Quantity of this handling unit", "example": 2 }, "length": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "m_unit": { "type": "string", "nullable": true, "description": "Length/width/height unit", "enum": [ "cm", "inch" ], "example": "cm" }, "weight_piece": { "type": "number", "nullable": true, "description": "Weight of one piece. Some flows also accept `total_kg` / `total_lbs`." }, "w_unit": { "type": "string", "nullable": true, "description": "Weight unit. Typical values: `kg`, `lbs`.\nSome flows use `total_kg` / `total_lbs`.\n", "enum": [ "kg", "lbs", "total_kg", "total_lbs" ], "example": "kg" }, "cbm_scope": { "type": "string", "nullable": true, "description": "Whether cubic measurements apply per piece or as a total", "enum": [ "piece", "total" ], "example": "piece" }, "container_type": { "type": "string", "nullable": true, "description": "Integer stored as a string. Used when `handling_unit` is `container`.\n\n| Value | Meaning |\n| --- | --- |\n| 1 | 20ft Standard |\n| 2 | 20ft Open top |\n| 3 | 20ft Flatrack |\n| 4 | 20ft Flatrack Collapsible |\n| 5 | 20ft Platform |\n| 6 | 20ft Refrigerated |\n| 7 | 20ft Bulk |\n| 8 | 20ft Tank |\n| 9 | 20ft Ventilated |\n| 10 | 40ft Standard |\n| 11 | 40ft Open top |\n| 12 | 40ft High-Cube |\n| 13 | 40ft Flatrack |\n| 14 | 40ft Flatrack collapsible |\n| 15 | 40ft Platform |\n| 16 | 40ft Refrigerated |\n| 17 | 45ft High-Cube |\n| 20 | 40ft HC Open top |\n| 21 | Pallet wide |\n| 22 | HC Refrigerated |\n| 23 | Double-Door |\n| 24 | Side-Opening |\n| 25 | 20ft Double-Door |\n| 26 | 20ft Side-Opening |\n", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "20", "21", "22", "23", "24", "25", "26" ], "example": "12" }, "temperature_control_required": { "type": "boolean", "nullable": true }, "temperature_control_value": { "type": "string", "nullable": true, "description": "Temperature band. If `6`, also set `temperature_controlled_custom_value`.\n\n| Value | Meaning |\n| --- | --- |\n| 1 | Deep frozen: <-20°C |\n| 2 | Store frozen: -20°C |\n| 3 | Store at 2°–8°C |\n| 4 | Cool: 8°–15°C |\n| 5 | Room temperature: 15°–25°C |\n| 6 | Other |\n", "enum": [ "1", "2", "3", "4", "5", "6" ] }, "temperature_controlled_custom_value": { "type": "string", "nullable": true, "description": "Required when `temperature_control_value` is `6` (Other)" }, "is_dangerous_good": { "type": "boolean", "nullable": true }, "dangerous_good_value": { "type": "string", "nullable": true, "description": "UN hazard class (string `\"1\"`…`\"9\"`).\n\n| Value | Meaning |\n| --- | --- |\n| 1 | Explosive |\n| 2 | Gases |\n| 3 | Flammable liquids |\n| 4 | Flammable solids |\n| 5 | Oxidising |\n| 6 | Toxic & infectious |\n| 7 | Radioactive |\n| 8 | Corrosives |\n| 9 | Miscellaneous |\n", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9" ] }, "nmfc_class": { "type": "string", "nullable": true, "description": "NMFC freight class", "enum": [ "50", "55", "60", "65", "70", "77.5", "85", "92.5", "100", "110", "125", "150", "175", "200", "250", "300", "400", "500" ], "example": "70" }, "hazardous": { "type": "boolean", "nullable": true }, "stackable": { "type": "boolean", "nullable": true }, "handling_required": { "type": "boolean", "nullable": true }, "crating_required": { "type": "boolean", "nullable": true }, "additional_information": { "type": "string", "nullable": true }, "good_customs_information": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/GoodCustomsInformation" } } } }, "StopBase": { "type": "object", "description": "Shared stop fields (canonical `schedule.stops[]`).\n\nInteger enums — **not** the classic string address / cargo-ready enums.\n\n| Field | Values |\n| --- | --- |\n| `stop_type` | `1` Pickup · `2` Dropoff / Delivery |\n| `stop_time_type` | `1` Before · `2` After · `3` Between · `4` ASAP |\n| `stop_address_type` | `1` Street address · `2` Airport · `3` Port / Seaport |\n\nPrefer `address_reference_number` (and/or `location_reference_number`)\nover `address_id`.\n", "properties": { "stop_type": { "type": "integer", "nullable": true, "enum": [ 1, 2 ], "description": "`1` = Pickup, `2` = Dropoff / Delivery", "example": 1 }, "stop_time_type": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, 4 ], "description": "`1` = Before, `2` = After, `3` = Between, `4` = ASAP", "example": 2 }, "stop_address_type": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3 ], "description": "`1` = Street address, `2` = Airport, `3` = Port / Seaport", "example": 1 }, "stop_address_name": { "type": "string", "nullable": true }, "stop_street": { "type": "string", "nullable": true }, "stop_street_line2": { "type": "string", "nullable": true }, "stop_zipcode": { "type": "string", "nullable": true }, "stop_country_name": { "type": "string", "nullable": true, "description": "Country name or ISO 3166 alpha-2 / alpha-3 code" }, "stop_state_name": { "type": "string", "nullable": true, "description": "State / province (typically US, Mexico, Canada)" }, "stop_city_name": { "type": "string", "nullable": true }, "stop_airport_code": { "type": "string", "nullable": true, "description": "IATA airport code when `stop_address_type` is `2`", "example": "SIN" }, "stop_airport_name": { "type": "string", "nullable": true }, "stop_seaport_code": { "type": "string", "nullable": true, "description": "UN/LOCODE when `stop_address_type` is `3`", "example": "SGSIN" }, "stop_seaport_name": { "type": "string", "nullable": true }, "stop_contact_name": { "type": "string", "nullable": true }, "stop_contact_number": { "type": "string", "nullable": true }, "stop_contact_email": { "type": "string", "nullable": true, "format": "email" }, "stop_after_date": { "type": "string", "format": "date", "nullable": true, "description": "Used with `stop_time_type` After (`2`) or Between (`3`)" }, "stop_after_time": { "type": "string", "format": "time", "nullable": true }, "stop_before_date": { "type": "string", "format": "date", "nullable": true, "description": "Used with `stop_time_type` Before (`1`) or Between (`3`)" }, "stop_before_time": { "type": "string", "format": "time", "nullable": true }, "stop_hours_start": { "type": "string", "nullable": true, "description": "Location opening time, typically `HH:MM` or `HH:MM:SS`", "example": "08:00:00" }, "stop_hours_end": { "type": "string", "nullable": true, "description": "Location closing time, typically `HH:MM` or `HH:MM:SS`", "example": "17:00:00" }, "stop_timezone": { "type": "string", "nullable": true, "description": "IANA timezone name", "example": "Asia/Singapore" }, "stop_notes": { "type": "string", "nullable": true }, "address_reference_number": { "type": "string", "nullable": true, "description": "Address v2 `reference_number`. Preferred over `address_id`.", "example": "A12345678" }, "location_reference_number": { "type": "string", "nullable": true, "description": "ERP location code. Address v2 required to resolve.", "example": "ERP-WH-01" } } }, "StopInput": { "allOf": [ { "$ref": "#/components/schemas/StopBase" }, { "type": "object", "description": "Stop object for create or patch. Do **not** include `stop_key` —\nit is server-assigned (400 if sent).\n", "properties": { "address_id": { "type": "integer", "nullable": true, "writeOnly": true, "description": "Write-only optional FK to `company.Address`. Prefer\n`address_reference_number`. Never returned on read.\n" } } } ] }, "StopOutput": { "allOf": [ { "$ref": "#/components/schemas/StopBase" }, { "type": "object", "required": [ "stop_key" ], "properties": { "stop_key": { "type": "string", "readOnly": true, "description": "Server-assigned stop key (e.g. `pickup-1`)", "example": "pickup-1" } } } ] }, "ClassicAddressType": { "type": "string", "nullable": true, "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n", "enum": [ "address", "airport", "seaport" ] }, "CargoReadyPickup": { "type": "string", "nullable": true, "description": "Classic pickup cargo-ready window. **Not** used on `stops[]`.", "enum": [ "after", "between", "asap_delivery", "unspecified" ] }, "CargoReadyDelivery": { "type": "string", "nullable": true, "description": "Classic delivery cargo-ready window. **Not** used on `stops[]`.", "enum": [ "before", "between", "asap_delivery", "unspecified" ] }, "FormAddressContactType": { "type": "string", "nullable": true, "description": "Classic consignee / notify-party contact type. **Not** used on `stops[]`.", "enum": [ "consignee", "delivery", "custom" ] }, "PartyAddress": { "type": "object", "description": "Consignee or notify-party block. Uses **classic string enums**, not\nthe integer stop enums.\n", "properties": { "address_type": { "$ref": "#/components/schemas/ClassicAddressType" }, "form_address_contact_type": { "$ref": "#/components/schemas/FormAddressContactType" }, "name": { "type": "string", "nullable": true }, "street": { "type": "string", "nullable": true }, "street_line2": { "type": "string", "nullable": true }, "zipcode": { "type": "string", "nullable": true }, "city_name": { "type": "string", "nullable": true }, "state_name": { "type": "string", "nullable": true }, "country_name": { "type": "string", "nullable": true }, "contact_name": { "type": "string", "nullable": true }, "contact_number": { "type": "string", "nullable": true }, "contact_email": { "type": "string", "nullable": true, "format": "email" }, "airport_code": { "type": "string", "nullable": true }, "airport_name": { "type": "string", "nullable": true }, "seaport_code": { "type": "string", "nullable": true }, "seaport_name": { "type": "string", "nullable": true } }, "additionalProperties": true }, "ShipmentObject": { "type": "object", "description": "Shipment-level title, timers, and comments", "properties": { "title": { "type": "string", "nullable": true, "example": "SG warehouse to NL DC" }, "quoting_deadline_date": { "type": "string", "format": "date", "nullable": true, "description": "Quote deadline date" }, "quoting_deadline_time": { "type": "string", "format": "time", "nullable": true, "description": "Quote deadline time of day" }, "confirmation_date": { "type": "string", "format": "date", "nullable": true }, "confirmation_time": { "type": "string", "format": "time", "nullable": true }, "comments": { "type": "string", "nullable": true } } }, "OrganizationalObject": { "type": "object", "description": "Organizational / accounting fields for the draft", "properties": { "location": { "type": "string", "nullable": true, "description": "`cb_account_number` of the payment location", "example": "SL2963758" }, "invoice_location": { "type": "string", "nullable": true, "description": "Organizational unit that should receive provider invoices" }, "reason_code_group": { "type": "string", "nullable": true }, "reason_code": { "type": "string", "nullable": true }, "custom_field_01": { "type": "string", "nullable": true }, "custom_field_02": { "type": "string", "nullable": true }, "custom_field_03": { "type": "string", "nullable": true }, "custom_long_field_01": { "type": "string", "nullable": true }, "cost_center": { "type": "string", "nullable": true }, "goods_confirmation_type": { "type": "string", "nullable": true, "description": "Packing-list confirmation status", "enum": [ "Estimated", "Finalized" ], "example": "Estimated" }, "cost_recovery_required": { "type": "boolean", "nullable": true }, "custom_cost_recovery_field1": { "type": "string", "nullable": true }, "custom_cost_recovery_field2": { "type": "string", "nullable": true } } }, "ScheduleObject": { "type": "object", "description": "Routing. Canonical writes use `stops[]` (integer enums).\n\nOptional classic fields (`pickup_address_type`, `pickup_cargo_ready`,\n`delivery_cargo_ready`, `stop1_address_type`) use **string** enums and\nare not applied to `stops[]`.\n", "properties": { "multistop_instructions": { "type": "string", "nullable": true }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/StopInput" } }, "consignee": { "allOf": [ { "$ref": "#/components/schemas/PartyAddress" } ], "nullable": true }, "notify_party": { "allOf": [ { "$ref": "#/components/schemas/PartyAddress" } ], "nullable": true }, "pickup_address_type": { "$ref": "#/components/schemas/ClassicAddressType" }, "stop1_address_type": { "$ref": "#/components/schemas/ClassicAddressType" }, "pickup_cargo_ready": { "$ref": "#/components/schemas/CargoReadyPickup" }, "delivery_cargo_ready": { "$ref": "#/components/schemas/CargoReadyDelivery" } } }, "ScheduleObjectRead": { "allOf": [ { "$ref": "#/components/schemas/ScheduleObject" }, { "type": "object", "properties": { "stops": { "type": "array", "items": { "$ref": "#/components/schemas/StopOutput" } } } } ] }, "SpecialRequirementFlag": { "type": "object", "description": "One special-requirement toggle. Object keys (labels) come from\nlocation configuration — they are not a global enum.\n", "properties": { "value": { "type": "boolean", "description": "Whether this requirement is requested" }, "additional_information": { "type": "string", "nullable": true } }, "additionalProperties": true }, "ServiceObject": { "type": "object", "description": "Service, clearance, and insurance options", "properties": { "incoterms": { "type": "string", "nullable": true, "description": "Incoterms 2010/2020 code (`DAT` retained for compatibility; `DPU` is the 2020 successor)", "enum": [ "None", "EXW", "FCA", "CPT", "CIP", "DAT", "DAP", "DDP", "FAS", "FOB", "CFR", "CIF", "DPU" ], "example": "DAP" }, "incoterm_instructions": { "type": "string", "nullable": true }, "service_type": { "type": "string", "nullable": true, "description": "| Value | Meaning |\n| --- | --- |\n| DTD | Door to door |\n| DTP | Door to port |\n| PTP | Port to port |\n| PTD | Port to door |\n", "enum": [ "DTD", "DTP", "PTP", "PTD" ], "example": "DTD" }, "service_level": { "type": "string", "nullable": true, "description": "Requested transit service level in days, or `NA`", "enum": [ "1", "3", "5", "7", "NA" ], "example": "5" }, "export_clearance": { "type": "string", "nullable": true, "description": "| Value | Meaning |\n| --- | --- |\n| no | Not requested |\n| yes_other | Yes — arranged by another party |\n| yes_internal | Yes — arranged internally by the shipper |\n| yes_provider | Yes — provider should arrange |\n", "enum": [ "no", "yes_other", "yes_internal", "yes_provider" ] }, "transit_clearance": { "type": "string", "nullable": true, "description": "Same enum as `export_clearance`", "enum": [ "no", "yes_other", "yes_internal", "yes_provider" ] }, "import_clearance": { "type": "string", "nullable": true, "description": "Same enum as `export_clearance`", "enum": [ "no", "yes_other", "yes_internal", "yes_provider" ] }, "export_clearance_instructions": { "type": "string", "nullable": true }, "transit_clearance_instructions": { "type": "string", "nullable": true }, "import_clearance_instructions": { "type": "string", "nullable": true }, "insurance": { "type": "boolean", "nullable": true }, "insurance_instructions": { "type": "string", "nullable": true }, "special_requirements": { "type": "object", "nullable": true, "description": "Map of location-configured requirement labels to\n`{ \"value\": true|false, ... }`.\n", "additionalProperties": { "$ref": "#/components/schemas/SpecialRequirementFlag" } } } }, "InvitedModes": { "type": "object", "description": "Freight modes to invite. Booleans select each mode.\n\nWhen `road_freight` is `true`, `road_freight_option` is **required**.\n", "properties": { "OBC": { "type": "boolean", "nullable": true, "description": "On board courier" }, "air_charter": { "type": "boolean", "nullable": true }, "NFO": { "type": "boolean", "nullable": true, "description": "Next flight out" }, "regular_air": { "type": "boolean", "nullable": true }, "road_freight": { "type": "boolean", "nullable": true }, "ocean_freight": { "type": "boolean", "nullable": true }, "parcel": { "type": "boolean", "nullable": true }, "rail_freight": { "type": "boolean", "nullable": true }, "road_freight_option": { "type": "string", "nullable": true, "description": "Required when `road_freight` is `true`.\n\n| Value | Meaning |\n| --- | --- |\n| ftl | Full truck load |\n| ltl | Less than truck load |\n| ge | Ground expedite |\n| spe | Specialized (car haulers, flat-beds, dump truck) |\n| multi-stop | Multi-stop |\n| multi-drop | Multi-drop |\n", "enum": [ "ftl", "ltl", "ge", "spe", "multi-stop", "multi-drop" ] }, "custom": { "type": "array", "nullable": true, "description": "Company-specific custom mode entries", "items": { "type": "object", "additionalProperties": true } } } }, "InvitedProviders": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "string" }, "description": "Accepts provider ids, provider references, names, or slugs.\nResponse stores canonical provider references (e.g. `PT12345678`).\n" }, "parcel_accounts": { "type": "array", "items": { "type": "string" } } } }, "DraftCreateInput": { "type": "object", "description": "Full payload for creating a system draft. Do **not** send\n`other_attachments` or `bucket_attachments`; upload other-files after\ncreate via POST /api/1/requests/draft/{draft_id}/attachments/.\n", "properties": { "external_id": { "type": "string", "description": "External ERP identifier for this draft (e.g. `ERP_ID_{timestamp}`)", "example": "ERP_ID_1710000000" }, "shipment": { "$ref": "#/components/schemas/ShipmentObject" }, "organizational": { "$ref": "#/components/schemas/OrganizationalObject" }, "schedule": { "$ref": "#/components/schemas/ScheduleObject" }, "packing_list": { "type": "array", "items": { "$ref": "#/components/schemas/PackingListItem" } }, "service": { "$ref": "#/components/schemas/ServiceObject" }, "invited_modes": { "$ref": "#/components/schemas/InvitedModes" }, "invited_providers": { "$ref": "#/components/schemas/InvitedProviders" } } }, "DraftPatchInput": { "type": "object", "description": "Partial update payload. Only include fields you want to change.\nDeep-merged into the stored document.\n\nDo **not** send `other_attachments` or `bucket_attachments` — upload\nother-files via POST /api/1/requests/draft/{draft_id}/attachments/.\n", "properties": { "external_id": { "type": "string" }, "shipment": { "$ref": "#/components/schemas/ShipmentObject" }, "organizational": { "$ref": "#/components/schemas/OrganizationalObject" }, "schedule": { "$ref": "#/components/schemas/ScheduleObject" }, "packing_list": { "type": "array", "items": { "$ref": "#/components/schemas/PackingListItem" } }, "service": { "$ref": "#/components/schemas/ServiceObject" }, "invited_modes": { "$ref": "#/components/schemas/InvitedModes" }, "invited_providers": { "$ref": "#/components/schemas/InvitedProviders" } } }, "DraftDocument": { "type": "object", "description": "Full stored draft document as returned by create / get / patch", "properties": { "draft_reference_number": { "type": "string", "readOnly": true, "description": "Server-assigned draft reference number", "example": "D12345678" }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "modified": { "type": "string", "format": "date-time", "readOnly": true }, "has_validation_errors": { "type": "boolean", "readOnly": true }, "external_id": { "type": "string", "nullable": true }, "shipment": { "$ref": "#/components/schemas/ShipmentObject" }, "organizational": { "$ref": "#/components/schemas/OrganizationalObject" }, "schedule": { "$ref": "#/components/schemas/ScheduleObjectRead" }, "packing_list": { "type": "array", "items": { "$ref": "#/components/schemas/PackingListItem" } }, "service": { "$ref": "#/components/schemas/ServiceObject" }, "invited_modes": { "$ref": "#/components/schemas/InvitedModes" }, "invited_providers": { "$ref": "#/components/schemas/InvitedProviders" }, "bucket_attachments": { "type": "array", "items": { "$ref": "#/components/schemas/BucketAttachment" }, "description": "Bucket attachment refs stored on the draft (read model). Not accepted on create/PATCH body in this API surface." }, "other_attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentRef" }, "description": "Other-file refs on the draft. Add new files via POST .../attachments/ (multipart). Not accepted on create/PATCH body." } } }, "ConvertDraftInput": { "type": "object", "properties": { "dry_run": { "type": "boolean", "description": "If true, validates without creating a shipment. Draft is retained.", "example": true }, "auto_select_all_providers": { "type": "boolean", "description": "Invite all eligible providers from the private pool" }, "skip_attachment_validation": { "type": "boolean", "description": "Skip attachment completeness checks during convert/dry-run" } } }, "DryRunSuccess": { "type": "object", "required": [ "valid", "draft_id" ], "properties": { "valid": { "type": "boolean", "example": true }, "draft_id": { "type": "string", "description": "Draft reference that was validated (draft is retained)", "example": "D12345678" } } }, "ConvertSuccess": { "type": "object", "required": [ "shipment_reference", "shipment_id", "draft_reference_number" ], "properties": { "shipment_reference": { "type": "string", "description": "New quote-request / shipment reference (e.g. `S12345678`)", "example": "S12345678" }, "shipment_id": { "type": "integer", "description": "Numeric shipment id", "example": 12345678 }, "draft_reference_number": { "type": "string", "description": "Draft that was converted (row is deleted after success)", "example": "D12345678" } } }, "CreateOrderRequest": { "type": "object", "properties": { "quick_request": { "type": "object", "description": "Basic request details", "properties": { "title": { "type": "string", "example": "Shipment Title", "description": "Title of the order or request", "maxLength": 100 }, "comments": { "type": "string", "example": "Sample Test comments.", "description": "Additional comments or instructions", "maxLength": 2000 }, "external_id": { "type": "string", "example": "sample_external_id", "description": "External ID used to identify the order in external systems", "maxLength": 255 } } }, "organizational": { "type": "object", "description": "Organizational metadata for cost tracking and reporting", "required": [ "location" ], "properties": { "location": { "type": "string", "example": "L1234567", "description": "A reference to the 'location' the request is for, location references are shared by Cargobase.", "maxLength": 15 }, "cost_center": { "type": "string", "example": "CC12345", "description": "Associated cost center", "maxLength": 70 }, "reason_code": { "type": "string", "example": "RC67890", "description": "Code explaining reason for the shipment", "maxLength": 70 }, "reason_code_group": { "type": "string", "example": "RCG112233", "description": "Group categorization for reason code", "maxLength": 70 }, "custom_field_01": { "type": "string", "description": "User-defined custom field 1", "maxLength": 70, "example": "Custom Value 01" }, "custom_field_02": { "type": "string", "description": "User-defined custom field 2", "maxLength": 70, "example": "Custom Value 02" }, "custom_field_03": { "type": "string", "description": "User-defined custom field 3", "maxLength": 70, "example": "Custom Value 03" }, "custom_long_field_01": { "type": "string", "description": "Extended custom field", "example": "Custom Long Field 01" }, "goods_confirmation_type": { "type": "string", "description": "Goods confirmation type (Estimated or Finalized)", "enum": [ "Estimated", "Finalized" ], "example": "Finalized" } } }, "schedule": { "type": "object", "description": "Scheduling and location details for pickup and delivery", "properties": { "pickup_contact_name": { "type": "string", "maxLength": 70 }, "pickup_contact_phone": { "type": "string", "maxLength": 70 }, "pickup_contact_email": { "type": "string", "maxLength": 70 }, "pickup_address_type": { "type": "string", "enum": [ "Address", "Seaport", "Airport" ], "description": "Type of pickup address (e.g. Address, Seaport or Airport)", "maxLength": 20, "example": "Address" }, "pickup_address_name": { "type": "string", "description": "Name/label of pickup address", "example": "Main Warehouse" }, "pickup_company_name": { "type": "string", "description": "Name of the pickup company", "example": "Logistics Co." }, "pickup_city": { "type": "string", "example": "New York" }, "pickup_state": { "type": "string", "example": "NY" }, "pickup_country": { "type": "string", "example": "USA" }, "pickup_zipcode": { "type": "string", "maxLength": 100 }, "pickup_airport_code": { "type": "string", "description": "IATA code of pickup airport", "maxLength": 70, "example": "JFK" }, "pickup_airport": { "type": "string", "maxLength": 70, "example": "John F. Kennedy International Airport" }, "pickup_seaport": { "type": "string", "maxLength": 70, "example": "Port of New York" }, "pickup_seaport_code": { "type": "string", "maxLength": 70, "example": "NYK" }, "pickup_country_code": { "type": "string", "maxLength": 70, "example": "US" }, "pickup_before_date": { "type": "string", "format": "date", "description": "Latest acceptable pickup date", "example": "2024-07-20" }, "pickup_before_time": { "type": "string", "description": "Latest acceptable pickup time", "example": "16:00:00" }, "pickup_ready_date": { "type": "string", "format": "date", "description": "Earliest pickup readiness date", "example": "2024-07-15" }, "pickup_ready_time": { "type": "string", "description": "Earliest pickup readiness time", "example": "08:00:00" }, "pickup_hours_from": { "type": "string", "description": "Pickup window start time", "example": "08:00:00" }, "pickup_hours_to": { "type": "string", "description": "Pickup window end time", "example": "17:00:00" }, "pickup_timezone": { "type": "string", "description": "Timezone for pickup", "example": "EST", "maxLength": 50 }, "pickup_cargo_ready": { "type": "string", "description": "Type of pickup time for the cargo. E.g. after specified pickup time, before specified pickup time, date range etc.", "enum": [ "after", "before", "between", "asap_delivery", "unspecified" ], "example": "after" }, "pickup_notes": { "type": "string", "description": "Notes for pickup location", "example": "Handle with care", "maxLength": 200 }, "pickup_street_line2": { "type": "string", "example": "Building B", "maxLength": 200 }, "delivery_hours_from": { "type": "string", "description": "Delivery window start time", "example": "09:00:00" }, "delivery_hours_to": { "type": "string", "description": "Delivery window end time", "example": "18:00:00" }, "stop1_address_type": { "type": "string", "description": "Delivery address type", "example": "Residential", "maxLength": 20 }, "stop1_company_name": { "type": "string", "example": "Recipient Corp.", "maxLength": 200 }, "stop1_notes": { "type": "string", "example": "Leave at front door", "maxLength": 200 }, "stop1_street_line2": { "type": "string", "example": "Apt 5B", "maxLength": 200 }, "stop1_street": { "type": "string", "example": "1234 Elm St", "maxLength": 200 }, "pickup_street": { "type": "string", "example": "5678 Oak St", "maxLength": 200 }, "stop1_country": { "type": "string", "example": "USA", "maxLength": 100 }, "stop1_state": { "type": "string", "example": "CA", "maxLength": 100 }, "stop1_country_code": { "type": "string", "example": "US", "maxLength": 70 }, "stop1_zipcode": { "type": "string", "example": "90001", "maxLength": 100 }, "stop1_city": { "type": "string", "example": "Los Angeles", "maxLength": 100 }, "stop1_address_name": { "type": "string", "example": "Recipient Home", "maxLength": 200 }, "stop1_contact_name": { "type": "string", "description": "Contact person at delivery location", "example": "Jane Doe", "maxLength": 70 }, "stop1_contact_phone": { "type": "string", "example": "555-1234", "maxLength": 70 }, "stop1_contact_email": { "type": "string", "example": "jane.doe@example.com", "maxLength": 70 }, "stop1_after_date": { "type": "string", "format": "date", "description": "Earliest delivery date", "example": "2024-07-22" }, "stop1_after_time": { "type": "string", "example": "10:00:00" }, "stop1_before_date": { "type": "string", "format": "date", "description": "Latest delivery date", "example": "2024-07-23" }, "stop1_before_time": { "type": "string", "example": "16:00:00" }, "stop1_timezone": { "type": "string", "example": "PST", "maxLength": 50 }, "delivery_cargo_ready": { "type": "string", "example": "Before", "enum": [ "after", "before", "between", "asap_delivery", "unspecified" ] }, "stop1_airport_code": { "type": "string", "example": "LAX", "maxLength": 70 }, "stop1_airport": { "type": "string", "example": "Los Angeles International Airport", "maxLength": 70 }, "stop1_seaport_code": { "type": "string", "example": "LAX", "maxLength": 10 }, "stop1_seaport": { "type": "string", "example": "Port of Los Angeles", "maxLength": 70 } } }, "packing_list": { "type": "array", "description": "List of goods/items to be shipped", "items": { "type": "object", "properties": { "handling_unit": { "type": "string", "description": "Type of handling unit (e.g., Pallet, Crate)", "example": "Pallet" }, "handling_unit_value": { "type": "string", "description": "Value or count of handling units", "example": "1" }, "units": { "type": "integer", "description": "Number of items or boxes", "example": 10 }, "length": { "type": "number", "description": "Length in meters", "example": 1.2 }, "width": { "type": "number", "description": "Width in meters", "example": 0.8 }, "height": { "type": "number", "description": "Height in meters", "example": 1 }, "m_unit": { "type": "string", "description": "Unit of measure for dimensions", "example": "meters" }, "hazardous": { "type": "boolean", "description": "Indicates if contents are hazardous", "example": false }, "container_type": { "type": "string", "example": "Standard" }, "temperature_control_required": { "type": "boolean", "example": true }, "temperature_control_value": { "type": "string", "example": "3" }, "temperature_controlled_custom_value": { "type": "string", "example": "Store at 5°C" }, "cbm_scope": { "type": "string", "description": "Cubic meter scope (Full/Partial)", "example": "Full" }, "l_w_h_cbm_total": { "type": "number", "description": "Total volume in CBM", "example": 0.96 }, "l_w_h_cbm_piece": { "type": "number", "description": "Volume per piece in CBM", "example": 0.096 }, "weight_piece": { "type": "number", "example": 50 }, "weight_total": { "type": "string", "example": "500.0" }, "w_unit": { "type": "string", "example": "kg" }, "stackable": { "type": "boolean", "example": true }, "is_dangerous_good": { "type": "boolean", "example": false }, "dangerous_good_value": { "type": "string", "example": "" }, "additional_information": { "type": "string", "example": "Handle with care" }, "crating_required": { "type": "boolean", "example": true }, "crating_required_by": { "type": "string", "format": "date", "example": "2024-07-20" }, "additional_text": { "type": "string", "example": "Ensure packaging integrity" }, "nmfc_class": { "type": "string", "example": "Class 70" }, "good_customs_information": { "type": "array", "description": "Customs data for goods", "items": { "type": "object", "properties": { "value": { "type": "number", "format": "float", "description": "Monetary value of the item", "example": 8000 }, "currency_code": { "type": "string", "description": "3-letter ISO code of currency of the value of the item", "example": "USD" }, "description": { "type": "string", "description": "Description of the item", "example": "Gear R" }, "hs_code": { "type": "string", "description": "HS Code of the item", "example": "E2" } } }, "example": [ { "value": 8000, "currency_code": "USD", "description": "Gear R", "hs_code": "E2" } ] }, "additional_field": { "type": "string", "example": "Extra details" } } }, "example": [ { "handling_unit": "Pallet", "handling_unit_value": "1", "units": 10, "length": 1.2, "width": 0.8, "height": 1, "m_unit": "meters", "hazardous": false, "container_type": "Standard", "temperature_control_required": true, "temperature_control_value": "3", "temperature_controlled_custom_value": "Store at 5°C", "cbm_scope": "Full", "l_w_h_cbm_total": 0.96, "l_w_h_cbm_piece": 0.096, "weight_piece": 50, "weight_total": "500.0", "w_unit": "kg", "stackable": true, "is_dangerous_good": false, "dangerous_good_value": "", "additional_information": "Handle with care", "crating_required": true, "crating_required_by": "2024-07-20", "additional_text": "Ensure packaging integrity", "nmfc_class": "Class 70", "good_customs_information": [ { "value": 8000, "currency_code": "USD", "description": "Gear R", "hs_code": "E2" } ], "additional_field": "Extra details" } ] }, "service": { "type": "object", "description": "Service-related options and instructions", "properties": { "incoterms": { "nullable": true, "type": "string", "description": "Incoterms used for the shipment", "example": null }, "incoterm_instructions": { "type": "string", "example": "" }, "service_level": { "type": "string", "example": "" }, "service_type": { "nullable": true, "type": "string", "example": null }, "export_clearance": { "type": "string", "description": "Export clearance requirement", "example": "API_NO_IMPORT_EXPORT_CLEARANCE" }, "export_clearance_instructions": { "type": "string", "example": "" }, "transit_clearance": { "type": "string", "description": "Transit clearance requirement", "example": "API_NO_IMPORT_EXPORT_CLEARANCE" }, "transit_clearance_instructions": { "type": "string", "example": "" }, "import_clearance": { "type": "string", "description": "Import clearance requirement", "example": "API_NO_IMPORT_EXPORT_CLEARANCE" }, "import_clearance_instructions": { "type": "string", "example": "" }, "insurance": { "nullable": true, "type": "string", "description": "Insurance information (if any)", "example": null }, "insurance_instructions": { "type": "string", "example": "" }, "special_requirements": { "type": "object", "description": "Additional special instructions or metadata" } } } } }, "DraftAttachmentUploadInput": { "type": "object", "description": "Multipart form fields for POST /api/1/requests/draft/{draft_id}/attachments/.", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload (same type rules as common file upload)." }, "filename": { "type": "string", "nullable": true, "maxLength": 150, "description": "Optional display name override.", "example": "extra.pdf" } } }, "DraftAttachmentUploadOutput": { "type": "object", "description": "Public upload receipt. Omits storage URL, DB id, and file size. The file is also appended onto the draft `other_attachments` array.", "required": [ "name", "reference_number", "file_extension" ], "properties": { "name": { "type": "string", "example": "extra.pdf" }, "reference_number": { "type": "string", "example": "FU12345678" }, "file_extension": { "type": "string", "example": "pdf" } } }, "CarrierTrackingWebhookPayload": { "type": "object", "required": [ "tracking_number", "tracking_type", "tracking_update_text", "tracking_status_tag" ], "x-conditional-required": [ { "if": { "tracking_status_tag": "DELIVERED" }, "then": [ "actual_arrival_time" ] } ], "properties": { "tracking_number": { "type": "string", "minLength": 1, "description": "Carrier / third-party tracking number that identifies this update. Updates are grouped and de-duplicated by tracking number.", "example": "OMNI-12345" }, "tracking_type": { "type": "string", "description": "Free-text identifier for the source of the update, for example `primary` or your carrier slug. Use one stable value for your system. Not validated on this endpoint.", "example": "primary" }, "tracking_update_text": { "type": "string", "description": "Human-readable description of the event, shown on the shipment timeline. When uploading a document, include the document type (POD, ARN, HBL, …). Used for duplicate detection.", "example": "Departed origin" }, "tracking_status_tag": { "type": "string", "description": "Normalized status for the event. Case-sensitive: send the uppercase value exactly as listed (`Delivered` or `intransit` is rejected). `DELIVERED` requires `actual_arrival_time`. See the status table in the operation description.", "enum": [ "BOOKED", "INTRANSIT", "DELAYED", "DELIVERED", "CANCELLED", "UNSPECIFIED" ], "example": "INTRANSIT" }, "mode_of_transport": { "type": "string", "description": "Freight mode for the shipment. Also decides which `milestone_details.event_type` values are accepted.", "enum": [ "air_freight", "road_freight", "ocean_freight", "rail_freight", "parcel_freight" ], "example": "air_freight" }, "shipment_id": { "type": "string", "description": "Cargobase shipment reference (for example `S22316102`). Strongly recommended: without it the update is stored against the tracking number only, and the Cargobase shipment's status and timings are not updated.", "example": "S22316102" }, "created_time": { "type": "string", "format": "date-time", "description": "When the event was recorded in your system (ISO 8601). Used as the event's timestamp on the shipment timeline; if omitted, the time Cargobase receives the update is used. Also used for duplicate detection, so send it to make retries safe (see *Duplicate updates*).", "example": "2026-09-30T08:10:00.000Z" }, "event_time": { "type": "string", "format": "date-time", "description": "When the milestone occurred (ISO 8601). Include `Z` or an offset; times without one are stored without a timezone.", "example": "2026-09-30T08:15:00.000Z" }, "event_time_with_timezone": { "type": "string", "format": "date-time", "description": "Same as `event_time`, with an explicit timezone offset when available.", "example": "2026-09-30T10:15:00.000+02:00" }, "expected_departure_time": { "type": "string", "format": "date-time", "description": "Expected departure (ISO 8601). Updates the shipment's expected departure when `shipment_id` is set.", "example": "2026-09-30T12:00:00.000Z" }, "expected_arrival_time": { "type": "string", "format": "date-time", "description": "Expected arrival / delivery (ISO 8601). Updates the shipment's expected arrival when `shipment_id` is set. Useful on in-transit updates.", "example": "2026-10-02T16:00:00.000Z" }, "actual_departure_time": { "type": "string", "format": "date-time", "description": "Actual departure (ISO 8601). Updates the shipment's actual departure when `shipment_id` is set.", "example": "2026-09-30T12:05:00.000Z" }, "actual_arrival_time": { "type": "string", "format": "date-time", "description": "Actual arrival / delivery (ISO 8601). **Required when `tracking_status_tag` is `DELIVERED`.** Updates the shipment's actual arrival when `shipment_id` is set.", "example": "2026-01-08T07:19:00.000Z" }, "pod_acceptor": { "type": "string", "description": "Name of the person who signed for the delivery. Recorded on the shipment with `DELIVERED` updates.", "example": "Jane Doe" }, "additional_info": { "type": "object", "description": "Free-form key/value object for extra carrier-specific data. Must be a JSON object (not an array or string).", "additionalProperties": true, "example": { "lane": "SIN-AMS", "vehicle_id": "TRK-44" } }, "bill_of_lading": { "type": "object", "description": "Bill of lading / ocean identifiers.", "properties": { "bill_of_lading_number": { "type": "string", "description": "Bill of lading (B/L) number.", "example": "COSU6349613240" }, "carrier_no": { "type": "string", "description": "SCAC code identifying the carrier.", "example": "COSU" }, "container_no": { "type": "string", "description": "Container number (container shipments only).", "example": "BMOU1589176" } } }, "flight_information": { "type": "object", "description": "Flight identifiers for air shipments. If you send this object, `flight_number` is required.", "required": [ "flight_number" ], "properties": { "flight_number": { "type": "string", "description": "Flight number including the airline code.", "example": "MH197" }, "airline": { "type": "string", "description": "Airline name.", "example": "Malaysia Airlines" } } }, "location": { "allOf": [ { "$ref": "#/components/schemas/CarrierTrackingLocation" } ], "description": "Where this event happened. `location.location_text` is shown on the timeline." }, "from": { "allOf": [ { "$ref": "#/components/schemas/CarrierTrackingLocation" } ], "description": "Origin / from location for the segment." }, "to": { "allOf": [ { "$ref": "#/components/schemas/CarrierTrackingLocation" } ], "description": "Destination / to location for the segment." }, "event_weight": { "type": "integer", "description": "Weight associated with this event. Whole number; decimal strings such as `\"12.5\"` are rejected.", "example": 2473 }, "event_piece": { "type": "integer", "description": "Piece count associated with this event (whole number).", "example": 12 }, "weight": { "type": "integer", "description": "Total weight for this tracking number (whole number).", "example": 2473 }, "piece": { "type": "integer", "description": "Total piece count for this tracking number (whole number).", "example": 12 }, "milestone_details": { "type": "object", "description": "Optional structured milestone. If you send this object, `event_type` and `location_type` are required. Allowed `event_type` values depend on `mode_of_transport`.", "required": [ "event_type", "location_type" ], "properties": { "event_type": { "type": "string", "description": "Milestone type, lowercase and exact. Checked when `mode_of_transport` is `ocean_freight`, `rail_freight` or `road_freight`; any value is accepted for `air_freight`, `parcel_freight`, or when `mode_of_transport` is omitted. See *Allowed milestone_details.event_type values* in the operation description.", "example": "departed", "x-event-types": { "ocean_freight": { "validated": true, "values": [ "booked", "pickup", "gatein", "load", "depart", "arrive", "unload", "gateout", "deliver", "return", "pod_berthing", "ts_berthing", "unclassified" ] }, "rail_freight": { "validated": true, "values": [ "booked", "pickup", "gatein", "load", "depart", "arrive", "unload", "gateout", "deliver", "return", "pod_berthing", "ts_berthing", "unclassified" ] }, "road_freight": { "validated": true, "values": [ "booked", "pickup", "departure", "pre_customs_clearance", "customs_check_in", "customs_clearance", "arrival", "unloading", "delivery" ] }, "air_freight": { "validated": false, "values": [ "booked_for_transport", "consignment_received", "received_from_shipper", "manifested_on_flight", "departed", "transferred_to_another_airline", "received_from_another_airline", "received_from_flight", "arrived_at_destination", "consignee_notified_of_arrival", "documentation_delivered_to_consignee", "consignment_to_be_transferred", "consignment_cleared_by_customs", "delivered_to_consignee", "discrepancy_details", "prepared_for_loading_on_flights", "documentation_received", "freight_on_hand", "freight_waybill_process" ] }, "parcel_freight": { "validated": false, "values": [] } } }, "location_type": { "type": "string", "description": "Which point of the journey this milestone refers to.", "enum": [ "place_of_receipt", "place_of_loading", "place_of_transhipment", "place_of_discharge", "place_of_delivery", "other" ], "example": "place_of_loading" }, "initial_quoted_time": { "type": "string", "format": "date-time", "description": "Time originally quoted for this milestone (ISO 8601)." }, "confirmed_time": { "type": "string", "format": "date-time", "description": "Time confirmed by the carrier (ISO 8601)." }, "estimated_time": { "type": "string", "format": "date-time", "description": "Current estimated time (ISO 8601)." }, "actual_time": { "type": "string", "format": "date-time", "description": "When the milestone actually happened (ISO 8601)." } } }, "routes": { "type": "array", "description": "Optional multi-leg route details. Every route object must include the `from` key (send `null` if unknown).", "items": { "type": "object", "description": "One leg of a multi-leg route.", "required": [ "from" ], "properties": { "sequence_id": { "type": "string", "description": "Order of this leg in the route.", "example": "1" }, "flight_number": { "type": "string", "description": "Flight number for this leg (air).", "example": "MH197" }, "transport_type": { "type": "string", "description": "Transport type for this leg. Free text.", "example": "flight" }, "status": { "type": "string", "description": "Status of this leg. Free text.", "example": "departed" }, "piece": { "type": "integer", "description": "Piece count on this leg (whole number).", "example": 12 }, "weight": { "type": "integer", "description": "Weight on this leg (whole number).", "example": 2473 }, "from": { "allOf": [ { "$ref": "#/components/schemas/CarrierTrackingLocation" } ], "description": "Start of this leg. The key is required; send `null` if unknown.", "nullable": true }, "to": { "allOf": [ { "$ref": "#/components/schemas/CarrierTrackingLocation" } ], "description": "End of this leg." }, "departure_datetime": { "type": "object", "description": "Departure times for this leg.", "properties": { "actual": { "type": "string", "format": "date-time", "description": "Actual departure (ISO 8601).", "example": "2026-09-30T12:05:00.000Z" }, "estimated": { "type": "string", "format": "date-time", "description": "Estimated departure (ISO 8601).", "example": "2026-09-30T12:00:00.000Z" } } }, "arrival_datetime": { "type": "object", "description": "Arrival times for this leg.", "properties": { "actual": { "type": "string", "format": "date-time", "description": "Actual arrival (ISO 8601).", "example": "2026-09-30T12:05:00.000Z" }, "estimated": { "type": "string", "format": "date-time", "description": "Estimated arrival (ISO 8601).", "example": "2026-09-30T12:00:00.000Z" } } } } } } } }, "CreateShipmentTrackingReference": { "type": "object", "required": [ "tracking_type", "tracking_number" ], "properties": { "tracking_type": { "type": "string", "description": "Tracking reference type. Currently only `primary` is supported.", "enum": [ "primary" ], "example": "primary" }, "tracking_number": { "type": "string", "maxLength": 25, "description": "Tracking number to attach to the shipment.", "example": "1Z999AA10123456784" } } }, "CreateShipmentTrackingInput": { "type": "object", "required": [ "references" ], "properties": { "references": { "type": "array", "description": "One or more tracking numbers to add to the shipment.", "items": { "$ref": "#/components/schemas/CreateShipmentTrackingReference" }, "minItems": 1 } }, "example": { "references": [ { "tracking_type": "primary", "tracking_number": "1Z999AA10123456784" } ] } }, "CarrierTrackingWebhookMultipart": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "description": "Tracking payload as a JSON string. Same fields as CarrierTrackingWebhookPayload." }, "documents": { "type": "string", "format": "binary", "description": "Document file to attach (POD, ARN, HBL, etc.). Omit for a milestone-only update. Repeat this key for multiple files." } } }, "CarrierTrackingLocation": { "type": "object", "description": "Location of the tracking event or route stop.", "properties": { "location_text": { "type": "string", "description": "Free-text location label. Shown with the update on the shipment timeline and used for duplicate detection.", "example": "Singapore Changi" }, "name": { "type": "string", "description": "Location, airport or facility name.", "example": "Incheon International Airport" }, "country": { "type": "string", "description": "Country name.", "example": "Singapore" }, "country_code": { "type": "string", "description": "Two-letter ISO 3166-1 country code.", "example": "SG" }, "state": { "type": "string", "description": "State or province.", "example": "Arkansas" }, "unlocode": { "type": "string", "description": "UN/LOCODE (5 characters).", "example": "SGSIN" }, "iata_code": { "type": "string", "description": "IATA airport code (3 letters).", "example": "SIN" }, "icao_code": { "type": "string", "description": "ICAO airport code (4 letters).", "example": "WSSS" }, "coordinates": { "type": "object", "description": "Geo coordinates. If you send this object, both `lat` and `lng` are required.", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "format": "float", "description": "Latitude in decimal degrees.", "example": 1.3644 }, "lng": { "type": "number", "format": "float", "description": "Longitude in decimal degrees.", "example": 103.9915 } } } } } }, "parameters": { "draft_id": { "name": "draft_id", "in": "path", "required": true, "description": "Draft reference number returned on create. Pattern: `SD` followed by digits (e.g. `SD12345678`).", "schema": { "type": "string", "pattern": "^SD[-\\d]+$" }, "example": "SD12345678" }, "stop_key": { "name": "stop_key", "in": "path", "required": true, "description": "Server-assigned stop key (e.g. `pickup-1`, `delivery-1`).", "schema": { "type": "string" }, "example": "pickup-1" } }, "responses": { "Unauthorized": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Authentication credentials were not provided." } } } }, "Forbidden": { "description": "Authenticated but not allowed to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "You do not have permission to perform this action." } } } }, "NotFound": { "description": "Draft or stop was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not found." } } } }, "ValidationError": { "description": "Field-level validation errors. Keys are field paths.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorBody" }, "examples": { "generic": { "summary": "Generic field errors", "value": { "schedule": { "stops": [ { "stop_type": [ "Invalid stop_type. Expected 1 (Pickup) or 2 (Dropoff/Delivery)." ] } ] } } }, "stopKeyNotAllowed": { "summary": "stop_key sent on write", "value": { "stop_key": [ "This field is server-assigned and must not be sent." ] } } } } } } }, "examples": { "DraftCreateFull": { "summary": "Typical create payload", "value": { "external_id": "ERP_ID_1710000000", "shipment": { "title": "SG warehouse to NL DC", "quoting_deadline_date": "2026-06-10", "quoting_deadline_time": "12:00:00", "confirmation_date": "2026-06-12", "confirmation_time": "12:00:00", "comments": "Handle as general cargo" }, "organizational": { "location": "SL2963758", "cost_center": "123.AB.44", "goods_confirmation_type": "Estimated", "cost_recovery_required": false }, "schedule": { "multistop_instructions": "Pickup first, then delivery", "stops": [ { "stop_type": 1, "stop_time_type": 2, "stop_address_type": 1, "stop_address_name": "SG Warehouse", "stop_street": "30 Example Road", "stop_zipcode": "654321", "stop_city_name": "Singapore", "stop_country_name": "Singapore", "stop_contact_name": "Warehouse Desk", "stop_contact_number": "+6511111111", "stop_contact_email": "warehouse@example.com", "stop_after_date": "2026-06-12", "stop_after_time": "10:00:00", "stop_timezone": "Asia/Singapore" }, { "stop_type": 2, "stop_time_type": 1, "stop_address_type": 1, "stop_address_name": "NL DC", "stop_street": "Wichersstraat 48", "stop_zipcode": "1051ML", "stop_city_name": "Amsterdam", "stop_country_name": "Netherlands", "stop_contact_name": "Max van Pankele", "stop_contact_number": "+31630645942", "stop_contact_email": "max@acmeinc.com", "stop_before_date": "2026-06-20", "stop_before_time": "17:00:00", "stop_timezone": "Europe/Amsterdam" } ] }, "packing_list": [ { "handling_unit": "pallet", "units": 2, "length": 120, "width": 80, "height": 100, "m_unit": "cm", "weight_piece": 250, "w_unit": "kg", "cbm_scope": "piece", "stackable": false, "hazardous": false, "is_dangerous_good": false, "temperature_control_required": false, "nmfc_class": "70", "good_customs_information": [ { "value": 8000, "currency_code": "USD", "description": "Spare parts", "hs_code": "8483.40" } ] } ], "service": { "incoterms": "DAP", "service_type": "DTD", "service_level": "5", "export_clearance": "yes_provider", "transit_clearance": "no", "import_clearance": "yes_other", "insurance": true, "insurance_instructions": "Full value coverage" }, "invited_modes": { "regular_air": true, "ocean_freight": false, "road_freight": false, "OBC": false, "NFO": false, "air_charter": false, "parcel": false, "rail_freight": false, "custom": [] } } } } }, "tags": [ { "name": "Quick Requests", "description": "## Operations\n\nEach name maps to its HTTP method and path:\n\n| Name | HTTP operation |\n| --- | --- |\n| List view | `GET /api/1/quickrequests/` |\n| Quick Request Detail | `GET /api/1/quickrequests/{qr_reference}/` |\n| Create Order | `POST /api/1/order/create/` |\n" }, { "name": "System Drafts", "description": "## Operations\n\nEach name maps to its HTTP method and path:\n\n| Name | HTTP operation |\n| --- | --- |\n| List Addresses | `GET /api/1/addresses` |\n| List view | `GET /api/1/requests/draft/` |\n| Create Draft | `POST /api/1/requests/draft/` |\n| Draft Detail | `GET /api/1/requests/draft/{draft_id}/` |\n| Update Draft | `PATCH /api/1/requests/draft/{draft_id}/` |\n| Upload Draft Attachment | `POST /api/1/requests/draft/{draft_id}/attachments/` |\n| Add Stop | `POST /api/1/requests/draft/{draft_id}/stops/` |\n| Update Stop | `PATCH /api/1/requests/draft/{draft_id}/stops/{stop_key}/` |\n| Delete Stop | `DELETE /api/1/requests/draft/{draft_id}/stops/{stop_key}/` |\n| Convert Draft | `POST /api/1/requests/draft/{draft_id}/create/` |\n\n# Description\nThe system draft end-points let shipper integrators create, inspect, patch, and convert **v4-style** quote-request drafts. Canonical routing uses `schedule.stops[]` (integer enums). Address v2 records can be discovered and applied via `address_reference_number` / `location_reference_number`.\n\n**Note** These new requests are considered DRAFT only until converted. Use convert with `dry_run: true` to validate without creating a shipment. On a successful convert, the draft row is deleted and a quote request is created.\n\n**Audience:** Shippers / ERP integrators \n**Authorization:** Cargobase provided Token\n\n# End-points\n* List Addresses (Shippers Only)\n* List Drafts (Shippers Only)\n* Create Draft (Shippers Only)\n* Draft Detail (Shippers Only)\n* Update Draft (Shippers Only)\n* Upload Draft Attachment (Shippers Only)\n* Add Stop (Shippers Only)\n* Update Stop (Shippers Only)\n* Delete Stop (Shippers Only)\n* Convert Draft / Dry Run (Shippers Only)\n\n## List Addresses (Shippers Only)\nDiscover Address v2 records for stop writes. Requires `is_new_address_enabled` on the company.\n**Request method:** GET \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token\n\n## List Drafts (Shippers Only)\nLightweight summary rows for accessible SYSTEM and REGULAR_NEXT_UI drafts.\n**Request method:** GET \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token\n\n## Create Draft (Shippers Only)\nCreate a system draft from a v4 payload (`schedule.stops[]`, packing list, service, invited modes). There is no hard minimum body beyond a valid JSON object; the more you send, the less UI cleanup is needed before convert.\n**Request method:** POST \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token\n\n## Draft Detail (Shippers Only)\nFetch the full stored draft document, including canonical `schedule.stops[]` (no `address_id`).\n**Request method:** GET \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token\n\n## Update Draft (Shippers Only)\nPartial update (deep-merge) of the draft document. Attachment arrays are not writable here — use Upload Draft Attachment for other-files.\n**Request method:** PATCH \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token\n\n## Upload Draft Attachment (Shippers Only)\nMultipart upload that creates a FileUpload and appends it to `other_attachments` on the draft.\n**Request method:** POST \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token\n\n## Add / Update / Delete Stop (Shippers Only)\nStop-level writes on `schedule.stops[]`. The server assigns `stop_key`; do not send it in the body.\n**Request methods:** POST, PATCH, DELETE \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token\n\n## Convert Draft / Dry Run (Shippers Only)\n`dry_run: true` validates without creating a shipment (draft retained). `dry_run: false` converts the draft into a quote request (draft deleted on success).\n**Request method:** POST \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token" }, { "name": "Quote Requests", "description": "## Operations\n\nEach name maps to its HTTP method and path:\n\n| Name | HTTP operation |\n| --- | --- |\n| Create Request | `POST /api/1/requests/create/` |\n| List view | `GET /api/1/requests/` |\n| Submit Quote | `POST /api/1/quotes/` |\n| Quotes List | `GET /api/1/quotes/` |\n| Update Request | `PUT /api/1/requests/{shipment_reference}/` |\n| Request Detail | `GET /api/1/requests/{shipment_reference}/` |\n| Assign team | `PUT /api/1/requests/{shipment_reference}/assign/` |\n| Update Quote | `PUT /api/1/quotes/{quotation_reference}/` |\n\n# Description\nThe quote requests end-points provide detail about currently active, or archived quote requests. \n**Note** It is important to understand, whenever a Request is awarded to a Provider, it is no longer considered a request, but rather a Shipment.\n\n# End-points\n* Create Request (Shippers Only)\n* Requests List\n* Request detail\n* Assign team\n* Submit quotes\n* Update quotes\n* Quotes list\n\n## Create Request (Shippers Only)\nThe Create Request end-point allows users to POST new requests to Cargobase. These new requests are then automatically forwarded to all available Logistics Service Providers from your private provider pool\n**Request method:** POST \n**Audience:** Shippers \n**Authorization:** Cargobase provided Token\n\n## Request List\nThe Request List is a straightforward end-point to display all currently active, canceled or uninvited requests. The response will contain all requests relevant to the user, paginated in descending order. \n**Request method:** GET \n**Audience:** Shippers, Providers \n**Authorization:** Cargobase provided Token \n\n## Request detail\nThe Request detail end-point allows a user to GET organizational, service, packing list and routing details. Shippers also have the ability to view quotes. \n**Request method:** GET \n**Audience:** Shippers, Providers \n**Authorization:** Cargobase provided Token\n\n## Assign team\nA simple end-point to assign a provider team. This is needed before submitting a quote, or in case a rate-card is available but multiple teams could apply for the same request.\n**Request method:** PUT \n**Audience:** Providers \n**Authorization:** Cargobase provided Token\n\n## Submit quotes\nThe Submit quotes end-point allows a provider user to POST quotes. \n**Request method:** POST \n**Audience:** Providers \n**Authorization:** Cargobase provided Token \n\n## Update quotes\nThe Updates quotes end-point allows a provider user to update previously submitted quotes. \n**Request method:** PUT \n**Audience:** Providers \n**Authorization:** Cargobase provided Token \n\n## Quotes list\nThe Quotes listl end-point allows a provider to view their quotes for a particular shipment.\n**Request method:** GET \n**Audience:** Providers \n**Authorization:** Cargobase provided Token" }, { "name": "Shipments", "description": "## Operations\n\nEach name maps to its HTTP method and path:\n\n| Name | HTTP operation |\n| --- | --- |\n| List view | `GET /api/1/shipments/` |\n| Shipment Detail | `GET /api/1/shipments/{shipment_reference}/` |\n| Cancel shipment | `PUT /api/1/shipments/{shipment_reference}/` |\n| Add tracking number | `POST /api/1/shipments/{shipment_reference}/tracking/create/` |\n\n# Description\nThe shipment end-points provide detail of active shipments. Providers can add tracking numbers and post tracking updates (see the Tracking tag).\n\n# End-points\n* Shipments\n* Shipment detail\n* Add tracking number\n\n## Shipments\nList of currently active Shipments associated with your account.\n* **Request method:** GET\n* **Audience:** Shippers, Providers\n* **Authorization:** Cargobase provided Token\n\n## Shipment detail\nView details of awarded shipments.\n* **Request method:** GET\n* **Audience:** Shippers, Providers\n* **Authorization:** Cargobase provided Token\n\n## Add tracking number\nAttach a tracking number to an awarded shipment.\n* **Request method:** POST `/api/1/shipments/{shipment_reference}/tracking/create/`\n* **Audience:** Providers / authorized tracking users\n* **Authorization:** Cargobase provided Token" }, { "name": "Invoices", "description": "## Operations\n\nEach name maps to its HTTP method and path:\n\n| Name | HTTP operation |\n| --- | --- |\n| List view | `GET /api/1/invoices/` |\n| Details | `GET /api/1/invoices/{invoice_reference}` |\n| Update Status | `POST /api/1/invoice-status-update/{invoice_reference}` |\n\n# Description\nThe Invoices end-points provide an overview of all invoices in a particular time frame and allows to view details of individual incoices.\n\n# End-points\n* Invoices\n* Invoice detail\n \n## Invoices\nInvoices is a list view of all invoices\n* **Request method:** GET.\n* **Audience:** Shippers, Providers.\n* **Authorization:** Cargobase provided Token.\n\n## Invoice detail\nThe Invoice detail end-point is a straightforward end-point to view details of submitted invoices.\n* **Request method:** GET.\n* **Audience:** Shippers, Providers.\n* **Authorization:** Cargobase provided Token." }, { "name": "Tracking", "description": "## Operations\n\nEach name maps to its HTTP method and path:\n\n| Name | HTTP operation |\n| --- | --- |\n| Post carrier tracking update | `POST /api/1/carrier-tracking-webhook` |\n\nPost carrier tracking milestones (and optional documents) via `POST /api/1/carrier-tracking-webhook`.\n\nRegister a tracking number with `POST /api/1/shipments/{shipment_reference}/tracking/create/`." } ], "paths": { "/api/1/quickrequests/": { "get": { "tags": [ "Quick Requests" ], "summary": "List view", "description": "The Quick Request List View end-point provides a list of Quick Requests associated with the requesting user. \nA Quick Request is a 'draft' version of a Quote request, therefore this end-point is only available to shippers.\n\n## Request URI\n\n```\nGET https://pluto.cargobase.com/api/1/quickrequests/\nContent-Type: application/json\nAuthorization: Token your_token_here\n\n```\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | OK | \\-- |\n| 403 | Forbidden | check Authentication token, or status of the request |\n\n## Request Response definition\n\n### Results (Main message)\n\n| Key | Value | Definition |\n| --- | --- | --- |\n| quick_request_reference | STRING | Cargobase Quick Request ID |\n| quick_request_title | STRING | Title of the Request, as provided by the Shipper |\n| status | STRING | Current status of the quick request, see list for potential status below |\n| pickup_city | STRING | The city name for Shipment pickup |\n| pickup_country | STRING | The country name for Shipment pickup |\n| stop1_city | STRING | The city name for the requested delivery location |\n| stop1_country | STRING | The country name for the requested delivery location |\n| related_shipment | STRING | A reference to the actual quote request or shipment, in case the quick request has been converted |\n\n#### Request status options\n\n| Status | Definition |\n| --- | --- |\n| Pending | A new quick request, that has not been converted into a quote request. |\n| Processing | A quick request that has been converted into a quote request |\n| Shipping | A quick request that has lead to a booked shipment |\n| Archived | A quick request that has been delivered or is canceled |\n\n### \"Header\"\n\n| Key | Value | Definition |\n| --- | --- | --- |\n| previous | STRING | URL to the previous page, in case page number is higher than 1 |\n| record_end | INTEGER | Number of the highest quick request on the page |\n| count | INTEGER | Total number of quick requests available to the user, across all pages |\n| page | INTEGER | Page number |\n| record_start | INTEGER | Number of the first quick request on the page |\n| next | STRING | URL to the previous page, in case page number is lower than the highest available |\n\n## Pagination\n\nThe request list results are paginated with 10 results per page by default. \nResults are displayed in descending order, that means that result 1 on page 1 is the newest addition. \nTo request a specific page append `?page=XX` to the URI. \nTo request a specific number of items per page, append `?page_size=xx` to the URI.\n\nResults can also be filtered to only display results of the account calling the API, this is done by appending '=self'.\n\n### Example\n\nCalling the API to show 25 results per page and viewing page 3 is\n\n```\nGET https://pluto.cargobase.com/api/1/quickrequests/?page_size=25&page=3\nContent-Type: application/json\nAuthorization: Token your_token_here\n\n```\n\n## Known issues\n\n* None at this moment!", "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "List view" } }, "/api/1/addresses": { "get": { "tags": [ "System Drafts" ], "operationId": "listAddresses", "summary": "List Addresses", "description": "Discover Address v2 records. Requires\n`is_new_address_enabled` on the company; returns 403 otherwise.\n\nUses the same availability scoping as draft address resolution.\nResponse is paginated AddressSerializer rows. Use returned\n`reference_number` and `location_reference_number` on stop writes.\n\n## Request URI\n\n```\nGET {ENV_DOMAIN}/api/1/addresses\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Query parameters\n\n| Key | Required | Definition |\n| --- | --- | --- |\n| `payment_location` | No | `cb_account_number`. Use `all` to list addresses across accessible payment locations. |\n| `query` | No | Search term (name, street, `location_reference_number`, etc.) |\n| `page` | No | Page number |\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | Paginated address list | — |\n| 401 | Unauthorized | Check `Authorization: Token …` |\n| 403 | Forbidden | Token invalid, or Address v2 is not enabled for the company |\n", "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "payment_location", "in": "query", "required": false, "description": "cb_account_number. Use `all` to list addresses across accessible payment locations.\n", "schema": { "type": "string" }, "example": "all" }, { "name": "query", "in": "query", "required": false, "description": "Search term (matches name, street, location_reference_number, etc.)", "schema": { "type": "string" }, "example": "Singapore" }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 } ], "responses": { "200": { "description": "Paginated list of address objects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAddressList" }, "example": { "count": 1, "results": [ { "reference_number": "A12345678", "location_reference_number": "ERP-WH-01", "name": "Warehouse Singapore", "street": "30 Example Road", "street_line2": null, "zipcode": "654321", "city_name": "Singapore", "state_name": null, "country_name": "Singapore", "contact_name": "Warehouse Desk", "contact_number": "+6511111111", "contact_email": "warehouse@example.com" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "List Addresses" } }, "/api/1/requests/draft/": { "get": { "tags": [ "System Drafts" ], "operationId": "listDrafts", "summary": "List view", "description": "List lightweight summary rows for accessible quote-request drafts\n(SYSTEM + REGULAR_NEXT_UI).\n\nSYSTEM rows use payment-location scope (including location peers).\nREGULAR_NEXT_UI rows are creator-only.\n\n## Request URI\n\n```\nGET {ENV_DOMAIN}/api/1/requests/draft/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Query parameters\n\n| Key | Required | Definition |\n| --- | --- | --- |\n| `external_id` | No | Return drafts matching this ERP / external id |\n\n## Response envelope\n\n`{ \"count\": N, \"results\": [ DraftSummary, … ] }`\n\n| Key | Type | Definition |\n| --- | --- | --- |\n| `draft_reference_number` | STRING | Server-assigned draft id (use as `{draft_id}`) |\n| `external_id` | STRING / null | Caller-supplied ERP identifier |\n| `created` | DATETIME | Creation timestamp |\n| `modified` | DATETIME | Last update timestamp |\n| `title` | STRING / null | From `shipment.title` |\n| `location` | STRING / null | Payment location (`cb_account_number`) |\n| `has_validation_errors` | BOOLEAN | Whether the stored draft currently fails convert validation |\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | Paginated draft summaries | — |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Check token / company access |\n", "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "external_id", "in": "query", "required": false, "description": "Filter — returns drafts matching this external id.", "schema": { "type": "string" }, "example": "ERP_ID_1710000000" } ], "responses": { "200": { "description": "Paginated list of draft summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDraftList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "List view" }, "post": { "tags": [ "System Drafts" ], "operationId": "createDraft", "summary": "Create Draft", "description": "Create a system draft using the canonical v4-style draft payload with\n`schedule.stops[]`.\n\nThere is **no minimum cargo/schedule payload** beyond a valid JSON\nobject and auth headers — the more you send, the less UI cleanup is\nneeded before convert. `{}` is not typical; send at least\n`external_id` plus the objects you know.\n\n`invited_providers.providers` accepts ids, provider references, names,\nor slugs. The stored/returned document uses **canonical provider\nreferences**.\n\nTo attach other-files, create the draft first, then upload with\n`POST /api/1/requests/draft/{draft_id}/attachments/` (multipart).\nDo **not** send `other_attachments` or `bucket_attachments` on create.\n\nSave the returned `draft_reference_number` as `{draft_id}` for later\ncalls.\n\n## Request URI\n\n```\nPOST {ENV_DOMAIN}/api/1/requests/draft/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Body — main objects\n\n| Category | Purpose |\n| --- | --- |\n| `external_id` | Your ERP identifier for this draft |\n| `shipment` | Title, quoting/confirmation timers, comments |\n| `organizational` | Location, cost center, reason codes, custom fields |\n| `schedule` | `stops[]` (canonical), plus optional consignee / notify party |\n| `packing_list` | Handling-unit lines |\n| `service` | Incoterms, service type/level, clearance, insurance |\n| `invited_modes` | Freight modes (and `road_freight_option` when road is invited) |\n| `invited_providers` | Optional provider / parcel-account targeting |\n\nDo **not** send `stop_key` on create-time stops — the server assigns\nkeys. `address_id` is write-only; prefer `address_reference_number`.\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 201 | Draft created — full document returned | Persist `draft_reference_number` |\n| 400 | Validation / malformed payload | See field errors in the body |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Check token / shipper access |\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftCreateInput" }, "examples": { "minimalExternalId": { "summary": "Minimal create with ERP id", "value": { "external_id": "ERP_ID_1710000000" } }, "fullCreate": { "summary": "Typical v4 create with two stops and one packing line", "$ref": "#/components/examples/DraftCreateFull" } } } } }, "responses": { "201": { "description": "Full draft document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDocument" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" } ], "x-displayName": "Create Draft" } }, "/api/1/requests/draft/{draft_id}/": { "get": { "tags": [ "System Drafts" ], "operationId": "getDraftDetail", "summary": "Draft Detail", "description": "Fetch the full v4-style draft document for an accessible\nquote-request draft (SYSTEM or REGULAR_NEXT_UI per access policy).\n\nReturns the stored payload including canonical `schedule.stops[]`\n(no `address_id`), `packing_list[]`, `other_attachments` (from the\nupload endpoint), `bucket_attachments` when present, and\n`invited_providers` as provider references.\n\n## Request URI\n\n```\nGET {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/\nAuthorization: Token your_token_here\n```\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | Full draft document | — |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Check token / access policy |\n| 404 | Draft not found | Check `draft_id` |\n", "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "$ref": "#/components/parameters/draft_id" } ], "responses": { "200": { "description": "Full draft document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDocument" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "Draft Detail" }, "patch": { "tags": [ "System Drafts" ], "operationId": "patchDraft", "summary": "Update Draft", "description": "Partial update of the whole draft document. Deep-merges this payload\ninto the existing draft, then persists canonical `schedule.stops[]`.\n\nReturns 200 with the full updated document on success.\n\n**Attachments:** do **not** send `other_attachments` or `bucket_attachments` on PATCH.\nUpload other-files with `POST /api/1/requests/draft/{draft_id}/attachments/`.\n\n## Request URI\n\n```\nPATCH {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | Full updated draft document | — |\n| 400 | Validation / malformed payload | See field errors |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Check token / access policy |\n| 404 | Draft not found | Check `draft_id` |\n", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "$ref": "#/components/parameters/draft_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftPatchInput" }, "examples": { "updateShipmentAndService": { "summary": "Update shipment title, service, and modes", "value": { "shipment": { "title": "Updated title", "comments": "Updated via PATCH" }, "organizational": { "cost_center": "Updated cost center", "invoice_location": null }, "service": { "service_type": "DTD", "incoterms": "DAP", "incoterm_instructions": "Delivered at place", "insurance": true, "insurance_instructions": "Full value coverage" }, "invited_modes": { "OBC": true, "NFO": true, "air_charter": false } } }, "patchProviders": { "summary": "Patch invited providers", "value": { "invited_providers": { "providers": [ "PT12345678" ], "parcel_accounts": [] } } } } } } }, "responses": { "200": { "description": "Full updated draft document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDocument" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "Update Draft" } }, "/api/1/requests/draft/{draft_id}/attachments/": { "post": { "tags": [ "System Drafts" ], "operationId": "uploadDraftAttachment", "summary": "Upload Draft Attachment", "description": "Multipart upload onto an existing system draft. Creates a FileUpload\nlinked to the draft and **appends** an entry to `other_attachments`.\n\nThis is the supported way to add new other-files after create.\nUses the same file-type validation as common file upload, and the\n`common_file_upload` throttle scope.\n\n## Request URI\n\n```\nPOST {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/attachments/\nContent-Type: multipart/form-data\nAuthorization: Token your_token_here\n```\n\n## Form fields\n\n| Field | Required | Definition |\n| --- | --- | --- |\n| `file` | Yes | Binary file |\n| `filename` | No | Optional display name (max 150) |\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 201 | Upload receipt (`name`, `reference_number`, `file_extension`) | File also on draft `other_attachments` |\n| 400 | Unsupported / invalid file | Check type and size |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Need create/edit quote-request permission |\n| 404 | Draft not found / inaccessible | Check `draft_id` |\n", "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "$ref": "#/components/parameters/draft_id" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DraftAttachmentUploadInput" }, "examples": { "withName": { "summary": "File plus display name", "description": "file is the binary part. filename is optional.", "value": { "filename": "packing-list.pdf" } } } } } }, "responses": { "201": { "description": "Upload receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftAttachmentUploadOutput" }, "example": { "name": "extra.pdf", "reference_number": "FU12345678", "file_extension": "pdf" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "Upload Draft Attachment" } }, "/api/1/requests/draft/{draft_id}/stops/": { "post": { "tags": [ "System Drafts" ], "operationId": "addStop", "summary": "Add Stop", "description": "Append a single stop to `schedule.stops[]`. The server assigns\n`stop_key`; do **not** send it in the body (400 if sent).\n\n`{}` is valid for a placeholder stop.\n\nReturns 201 with the public normalized stop object\n(`address_reference_number` when resolved; **no** `address_id`).\nCan also resolve by ERP `location_reference_number` (Address v2 required).\n\n## Request URI\n\n```\nPOST {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/stops/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Stop enums (integers)\n\n| Field | Values |\n| --- | --- |\n| `stop_type` | `1` Pickup · `2` Dropoff / Delivery |\n| `stop_time_type` | `1` Before · `2` After · `3` Between · `4` ASAP |\n| `stop_address_type` | `1` Street address · `2` Airport · `3` Port / Seaport |\n\nPrefer `address_reference_number` over write-only `address_id`.\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 201 | Public normalized stop object | Persist `stop_key` |\n| 400 | Bad request (e.g. `stop_key` sent in body) | Remove `stop_key`; check types |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Check token / access policy |\n| 404 | Draft not found | Check `draft_id` |\n", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "$ref": "#/components/parameters/draft_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopInput" }, "examples": { "placeholder": { "summary": "Empty placeholder stop", "value": {} }, "secondPickup": { "summary": "Street-address pickup with after time", "value": { "stop_type": 1, "stop_time_type": 2, "stop_address_type": 1, "stop_address_name": "Second Pickup", "stop_street": "30 Example Road", "stop_zipcode": "654321", "stop_country_name": "Singapore", "stop_city_name": "Singapore", "stop_contact_name": "Second Contact", "stop_contact_number": "+6511111111", "stop_contact_email": "second@example.com", "stop_after_date": "2026-06-12", "stop_after_time": "10:00:00", "stop_before_date": "2026-06-12", "stop_before_time": "10:00:00", "stop_timezone": "Asia/Singapore", "stop_notes": "Extra stop", "address_reference_number": null, "address_id": null, "location_reference_number": null } }, "resolveByLocationRef": { "summary": "Resolve address by ERP location reference", "value": { "stop_type": 2, "stop_address_type": 1, "location_reference_number": "ERP-WH-01" } } } } } }, "responses": { "201": { "description": "Public normalized stop object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopOutput" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "Add Stop" } }, "/api/1/requests/draft/{draft_id}/stops/{stop_key}/": { "patch": { "tags": [ "System Drafts" ], "operationId": "patchStop", "summary": "Update Stop", "description": "Partial update of one stop by `stop_key`. Do not send `stop_key` in\nthe body (400 if sent). Unknown stop returns 404.\n\nReturns 200 with the updated public stop object (includes\n`location_reference_number` when set; **no** `address_id`).\n\n## Request URI\n\n```\nPATCH {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/stops/{stop_key}/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | Updated public stop object | — |\n| 400 | Bad request (e.g. `stop_key` in body) | Remove `stop_key` |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Check token / access policy |\n| 404 | Stop or draft not found | Check `draft_id` and `stop_key` |\n", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "$ref": "#/components/parameters/draft_id" }, { "$ref": "#/components/parameters/stop_key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopInput" }, "examples": { "notes": { "summary": "Update notes and contact", "value": { "stop_notes": "Dock 3 only", "stop_contact_name": "Updated Contact" } }, "airport": { "summary": "Set an airport address", "description": "stop_address_type 2 is an airport.", "value": { "stop_address_type": 2, "stop_airport_code": "SIN", "stop_airport_name": "Singapore Changi" } }, "seaport": { "summary": "Set a seaport address", "description": "stop_address_type 3 is a port.", "value": { "stop_address_type": 3, "stop_seaport_code": "SGSIN", "stop_seaport_name": "Port of Singapore" } } } } } }, "responses": { "200": { "description": "Updated public stop object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopOutput" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "Update Stop" }, "delete": { "tags": [ "System Drafts" ], "operationId": "deleteStop", "summary": "Delete Stop", "description": "Remove one stop by `stop_key`. Returns 204.\n\nClears `pickup_stop_key` / `delivery_stop_key` on linked packing-list\nlines (sets them to `null`) but does **not** delete those lines.\n\n## Request URI\n\n```\nDELETE {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/stops/{stop_key}/\nAuthorization: Token your_token_here\n```\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 204 | Stop removed | — |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Check token / access policy |\n| 404 | Stop or draft not found | Check `draft_id` and `stop_key` |\n", "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "$ref": "#/components/parameters/draft_id" }, { "$ref": "#/components/parameters/stop_key" } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "Delete Stop" } }, "/api/1/requests/draft/{draft_id}/create/": { "post": { "tags": [ "System Drafts" ], "operationId": "convertDraftOrDryRun", "summary": "Convert Draft", "description": "Convert an accessible SYSTEM or REGULAR_NEXT_UI draft into a quote\nrequest, or validate the same rules without creating a shipment.\n\n### Dry run (`dry_run: true`)\n\nRuns full convert validation **without** creating a Shipment.\nDraft is retained.\n\n- Success: `200` `{ \"valid\": true, \"draft_id\": \"...\" }`\n- Failure: `400` with field errors\n\n### Convert (`dry_run` omitted or `false`)\n\nCreates the quote request. Draft row is **deleted** on success.\n\n- Success: `201` `{ shipment_reference, shipment_id, draft_reference_number }`\n- Failure: `400` with field errors (draft retained)\n\n## Request URI\n\n```\nPOST {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/create/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Body\n\n| Key | Type | Required | Purpose |\n| --- | --- | --- | --- |\n| `dry_run` | BOOLEAN | No | `true` = validate only; draft is kept |\n| `auto_select_all_providers` | BOOLEAN | No | Invite all eligible providers |\n| `skip_attachment_validation` | BOOLEAN | No | Skip attachment completeness checks |\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | Dry run succeeded — draft is valid | Proceed to convert when ready |\n| 201 | Draft converted to quote request | Persist `shipment_reference` |\n| 400 | Validation errors | Fix fields; draft is retained |\n| 401 | Unauthorized | Check token |\n| 403 | Forbidden | Check token / access policy |\n| 404 | Draft not found | Check `draft_id` |\n", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "$ref": "#/components/parameters/draft_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertDraftInput" }, "examples": { "dryRun": { "summary": "Validate without creating a shipment", "value": { "dry_run": true, "auto_select_all_providers": true, "skip_attachment_validation": false } }, "convert": { "summary": "Convert draft to quote request", "value": { "dry_run": false, "auto_select_all_providers": true, "skip_attachment_validation": false } } } } } }, "responses": { "200": { "description": "Dry run success — draft is valid and retained", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunSuccess" }, "example": { "valid": true, "draft_id": "D12345678" } } } }, "201": { "description": "Draft successfully converted to quote request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertSuccess" }, "example": { "shipment_reference": "S12345678", "shipment_id": 12345678, "draft_reference_number": "D12345678" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "x-displayName": "Convert Draft" } }, "/api/1/requests/create/": { "post": { "tags": [ "Quote Requests" ], "summary": "Create Request", "description": "The Request CREATE end-point can be used to generate quote requests on Cargobase. This end-point can be used to create and send out full quote requests to your freight forwarders. Based on the details provided, all available providers will be invited. This means that some data is mandatory.\n\nTypically, this end-point is used to connect automated systems, or systems in which the Cargobase functionality is fully integrated. For more generic implementations, such as with ERP systems, we strongly advise to review the *draft* end-point.\n\n**Note** This end-point only applies to Shippers\n\n## Request URI\n\n```\nPOST https://pluto.cargobase.com/api/1/requests/create\nContent-Type: application/json\nAuthentication: Token 'your_token_here'\n\n```\n\n## Body message\n\nBecause we generate a full request and invite available forwarders, there are some mandatory fields that need to be taken into account.\n\nThe message body is constructed around 3 main object categories and 3 subcategories. \nSome values are mandatory, others are optional\n\n### Main object categories\n\n| Category parameter | Purpose | Child object |\n| --- | --- | --- |\n| organization | Organizational detail, such as Cost center or Reason code | good_items & good_customs_items |\n| service | Details such as incoterms or freight modes | none |\n| schedule | Details such as locations or timing | none |\n\n### Body Sub-categories\n\n| Category parameter | Purpose | Parent object |\n| --- | --- | --- |\n| good_items | Specification of individual handling units | organization |\n| good_customs_items | Specification of commercial values or details of individual handling units | good_items |\n| special_requirements | Specification of commercial values or details of individual handling units | good_items |\n\n#### organization values\n\n| Key | Value | Mandatory | Purpose | Parent object |\n| --- | --- | --- | --- | --- |\n| location | STRING | MANDATORY | A reference to the 'location' the request is for, location references are shared by Cargobase | organization |\n| requestor_username | STRING | No | The username of a person to be listed as the initiator of the request, must be an active Cargobase account | organization |\n| quoting_deadline_date | STRING | MANDATORY | Quote deadline date (UTC time) in specified format YYYY-MM-DD | organization |\n| quoting_deadline_time | STRING | MANDATORY | Quote deadline time of day (UTC time) in specified format HH:MM | organization |\n| confirmation_date | STRING | MANDATORY | Confirmation time date (UTC time) in specified format YYYY-MM-DD | organization |\n| confirmation_time | STRING | MANDATORY | Confirmation time of day (UTC time) in specified format HH:MM | organization |\n| good_items | OBJECT | MANDATORY | see specification below | organization |\n| title | STRING | No | Posted as title of the shipment for easy reference | organization |\n| cost_center | STRING | No | Value of cost_center - can have custom label | organization |\n| custom_field1 | STRING | No | Value of custom_field1 - can have custom label | organization |\n| custom_field1 | STRING | No | Value of custom_field2 - can have custom label | organization |\n| custom_longfield_01 | STRING | No | Value of Custom_longfield_01, can have a custom label | organization |\n| reason_code | STRING | No | Value of custom_field1 - can have custom label | organization |\n| special_requirements | OBJECT | No | see specification below | organization |\n\n##### good_items\n\nEach request can have 1 or multiple goods on the packing list. These goods are described in 'good_item'-objects. \nA request can have multiple such objects.\n\n| Key | Value | Mandatory | Purpose |\n| --- | --- | --- | --- |\n| handling_unit | STRING | No | String of handling unit - see options below |\n| units | INT | No | Quantity of items of this type |\n| length | INT | No | Length in whole centimeters or inches |\n| width | INT | No | Width in whole centimeters or inches |\n| height | INT | No | Height in whole centimeters or inches |\n| m_unit | STRING | No | Unit of measurement for LxWxH can be \"cm\" or \"inch\" |\n| weight | INT | No | Weight in whole kgs or lbs |\n| w_unit | STRING | No | Unit of measurement for weight can be \"lbs\" or \"kg\" |\n| stackable | BOOLEAN | No | To indicate if unit is stackable |\n| hazardous | BOOLEAN | No | To indicate if unit is hazardous |\n| is_dangerous | BOOLEAN | No | To indicate if unit is classified as a dangerous good |\n| dangerous_goods_value | STRING | No | Reference number of the DG class, see table below for potential values |\n| container_type | STRING | No | Reference number of the container type, see table below for potential values |\n| refridgerated_container | BOOLEAN | No | To identify if container should be refridgerated, in case of handling unit container |\n| additional_information | STRING | No | Text description of additional information for this item |\n| goods_customs_information | OBJECT | No | OBJECT containing customs information for this item |\n\n##### handling_unit options\n\n* Bag\n* Box\n* Carton\n* Case\n* Crate\n* Container\n* Pallet\n* Tube\n \n\n**NOTE** Custom handling units are not supported at this moment.\n\n##### Dangerous goods value\n\n| Value | Description |\n| --- | --- |\n| 1 | DG 1: Explosive substances and articles |\n| 2 | DG 2: Gasses |\n| 3 | DG 3: Flammable liquids |\n| 4 | DG 4: Flammable solids |\n| 5 | DG 5: Oxidising substances |\n| 6 | DG 6: Toxic & Infectious substances |\n| 7 | DG 7: Radioactive material |\n| 8 | DG 8: Corrosives |\n| 9 | DG 9: Miscellaneous |\n\n##### Container type value\n\n| Value | Description |\n| --- | --- |\n| 1 | 20Ft Standard |\n| 2 | 20Ft Open top |\n| 3 | 20Ft Flatrack |\n| 4 | 20Ft Flatrack Collapsible |\n| 5 | 20Ft Platform |\n| 6 | 20Ft Refrigerated |\n| 7 | 20Ft Bulk |\n| 8 | 20Ft Tank |\n| 9 | 20Ft Ventilated |\n| 10 | 40Ft Standard |\n| 11 | 40Ft Open top |\n| 12 | 40Ft High-Cube |\n| 13 | 40Ft Flatrack |\n| 14 | 40Ft Flatrack collapsible |\n| 15 | 40Ft Platform |\n| 16 | 40Ft Refrigerated |\n| 17 | 45Ft High-Cube |\n| 18 | Custom size |\n| 19 | LCL |\n\n##### goods_customs_information\n\nEach good item can contain multiple goods, these goods are described in the 'goods_customs_information' object. \nA good item can have multiple such objects.\n\n| Key | Value | Purpose |\n| --- | --- | --- |\n| value | INTEGER | Monetary value of product in this handling unit |\n| currency_code | STRING | 3-letter ISO code of currency of the value of the item |\n| description | STRING | Description of item contents |\n| hs_code | STRING | HS Code of the item |\n\n##### special_requirements\n\nEach request can have special requirements, these are defined in the special_requirements object. \nEach request can only have 1 special requirements object. \nThis object is not a mandatory object for most, however - for some it is; in those cases, all booleans mentioned below are expected.\n\n| Key | Value | Purpose |\n| --- | --- | --- |\n| air_truck_required | BOOLEAN | Indication if this requirement is requested on the shipment |\n| air_truck_additional_information | STRING | Additional description of this requirement |\n| shock_tilt_required | BOOLEAN | Indication if this requirement is requested on the shipment |\n| shock_tilt_additional_information | STRING | Additional description of this requirement |\n| unique_handling_required | BOOLEAN | Indication if this requirement is requested on the shipment |\n| unique_handling_additional_information | STRING | Additional description of this requirement |\n| chemical_magnetic_concerns | BOOLEAN | Indication if this requirement is requested on the shipment |\n| chemical_magnetic_additional_information | STRING | Additional description of this requirement |\n| unique_warehousing_required | BOOLEAN | Indication if this requirement is requested on the shipment |\n| unique_warehousing_additional_information | STRING | Additional description of this requirement |\n| special_transport_required | BOOLEAN | Indication if this requirement is requested on the shipment |\n| special_transport_additional_information | STRING | Additional description of this requirement |\n| special_provider_requirements | BOOLEAN | Indication if this requirement is requested on the shipment |\n| special_provider_additional_information | STRING | Additional description of this requirement |\n| special_lift_fixtures_required | BOOLEAN | Indication if this requirement is requested on the shipment |\n| special_lift_fixtures_additional_information | STRING | Additional description of this requirement |\n\n#### service values\n\n| Key | Value | Mandatory | Purpose | Parent object |\n| --- | --- | --- | --- | --- |\n| incoterm | STRING | MANDATORY | Requested incoterms - see possible options below | service |\n| insurance | BOOLEAN | MANDATORY | To indicate if shipment insurance is requested | service |\n| insurance_instructions | STRING | No | Descriptive text of your request, in case set to 'true' | service |\n| service_requirement | MANDATORY | STRING | Indication of service requirement type - see options below | service |\n| export_clearance | BOOLEAN | MANDATORY | Indication if Export clearance is requested and how - see Clearance options below | service |\n| export_clearance_instructions | STRING | No | Descriptive text of your request, in case set to 'true' | service |\n| transit_clearance | BOOLEAN | MANDATORY | Indication if Transit clearance is requested and how - see Clearance options below | service |\n| transit_clearance_instructions | STRING | No | Descriptive text of your request, in case set to 'true' | service |\n| import_clearance | BOOLEAN | MANDATORY | Indication if Import clearance is requested and how - see Clearance options below | service |\n| import_clearance_instructions | STRING | No | Descriptive text of your request, in case set to 'true' | service |\n| air_charter_invited | BOOLEAN | MANDATORY | To indicate if Air charter forwarders should be invited | service |\n| next_flight_invited | BOOLEAN | MANDATORY | To indicate if Next flight out (NFO) forwarders should be invited | service |\n| ocean_freight_invited | BOOLEAN | MANDATORY | To indicate if Ocean freight forwarders should be invited | service |\n| rail_freight_invited | BOOLEAN | MANDATORY | To indicate if Rail freight forwarders should be invited | service |\n| regular_air_freight_invited | BOOLEAN | MANDATORY | To indicate if Regular Air freight forwarders should be invited | service |\n| road_freight_invited | BOOLEAN | MANDATORY | To indicate if Road freight forwarders should be invited | service |\n| road_freight_type | BOOLEAN | MANDATORY | Specification of road freight type, see options below | service |\n\n##### Incoterm options\n\n| Value | Description |\n| --- | --- |\n| EXW | Ex Works |\n| FCA | Free Carrier |\n| CPT | Carriage Paid To |\n| CIP | Carriage Insurance Paid to |\n| DAT | Delivery At Terminal |\n| DAT | Delivery At Place |\n| DDP | Delivery Duty Paid |\n| FAS | Free Along Ship |\n| FOB | Free On Board |\n| CFR | Cost and Freight |\n| CIF | Cost, Insurance and Freight |\n\n##### Service requirement options\n\n| Value | Description |\n| --- | --- |\n| DTD | Door-to-Door |\n| DTP | Door-to-Port |\n| PTD | Port-to-Door |\n| PTP | Port-to-Port |\n\n##### Clearance options\n\n| Value | Description |\n| --- | --- |\n| 1 | Maby requested, to be clarified in description |\n| 2 | Will be arrange by shipper, to be clarified in accompanying description |\n| 3 | Provider is requested to arrange, to be clarified in accompanying description |\n\n##### Road freight options\n\n| Value | Description |\n| --- | --- |\n| FTL | Full-truck load |\n| LTL | Less than Truck Load |\n| GROUND_EXPEDITE | Ground Expedite |\n| SPECIALIZED | Specialized - Car haulers, flat-beds, dump truck |\n| MULTI_STOP | Multi-stop |\n\n#### schedule values\n\n| Key | Value | Mandatory | Purpose | Parent object |\n| --- | --- | --- | --- | --- |\n| pickup_airport_code | STRING | CONDITIONAL | IATA Airport code, if identified otherwise `null` | schedule |\n| pickup_airport | STRING | CONDITIONAL | Airport Name, if identified otherwise `null` | schedule |\n| pickup_seaport_code | STRING | CONDITIONAL | Seaport code (UN/LOCODE), if identified otherwise `null` | schedule |\n| pickup_seaport | TYPE | CONDITIONAL | Seaport name, if identified otherwise `null` | schedule |\n| pickup_street | STRING | MANDATORY | Pickup street address | schedule |\n| pickup_address_name | STRING | MANDATORY | Pickup company name | schedule |\n| pickup_state | STRING | CONDITIONAL | The state/province in case of Canada, Mexico or USA, see below for value options | schedule |\n| pickup_zipcode | STRING | MANDATORY | The pickup postal code | schedule |\n| pickup_city | STRING | MANDATORY | The pickup city | schedule |\n| pickup_country | STRING | MANDATORY | The pickup country, see below for value options | schedule |\n| pickup_date | TIMESTAMP | MANDATORY | Requested pickup date (local time), format `YYYY-MM-DD` | schedule |\n| pickup_time | TIMESTAMP | MANDATORY | Requested pickup time (local time), format `HH:MM` | schedule |\n| pickup_time_type | INTEGER | MANDATORY | Requested pickup type can be `1=Regular`or `2=Between` | schedule |\n| pickup_end_date | TIMESTAMP | No | Requested pickup end date (local time), in case of pickup_time_type 2 | schedule |\n| pickup_end_time | TIMESTAMP | No | Requested pickup end time (local time), in case of pickup_time_type 2 | schedule |\n| pickup_hours_start | TIMESTAMP | No | If Shipper indicated pickup location opening hours format: `HH:MM` | schedule |\n| pickup_hours_end | TYPE | No | If Shipper indicated pickup location closing hours format: `HH:MM` | schedule |\n| pickup_notes | STRING | No | Additional pickup notes | schedule |\n| pickup_contact_name | STRING | MANDATORY | Name of contact person at pickup location | schedule |\n| pickup_contact_phone | STRING | MANDATORY | Phone number of contact person at pickup location | schedule |\n| pickup_contact_email | STRING | MANDATORY | Email of contact person at pickup location | schedule |\n| pickup_address_type | STRING | No | Can be `Address`, `Seaport` or `Airport` | schedule |\n| stop1_airport | STRING | CONDITIONAL | Airport Name, if identified otherwise `null` | schedule |\n| stop1_seaport_code | STRING | CONDITIONAL | Seaport code, if identified otherwise `null` | schedule |\n| stop1_seaport | TYPE | CONDITIONAL | Seaport name, if identified otherwise `null` | schedule |\n| stop1_street | STRING | MANDATORY | Delivery street address | schedule |\n| stop1_address_name | STRING | MANDATORY | Delivery company name | schedule |\n| stop1_state | STRING | CONDITIONAL | The state/province in case of Canada, Mexico or USA, see below for value options | schedule |\n| stop1_zipcode | STRING | MANDATORY | The delivery postal code | schedule |\n| stop1_city | STRING | MANDATORY | The delivery city | schedule |\n| stop1_country | STRING | MANDATORY | The delivery country, see below for value options | schedule |\n| stop1_date | TIMESTAMP | MANDATORY | Requested delivery date (local time), format `YYYY-MM-DD` | schedule |\n| stop1_time | TIMESTAMP | MANDATORY | Requested delivery time (local time), format `HH:MM` | schedule |\n| stop1_time_type | INTEGER | No | Requested delivery type can be `1=Regular`or `2=Between` | schedule |\n| stop1_end_date | TIMESTAMP | No | Requested delivery end date (local time), in case of stop1_time_type 2 | schedule |\n| stop1_end_time | TIMESTAMP | No | Requested delivery end time (local time), in case of stop1_time_type 2 | schedule |\n| stop1_hours_start | TIMESTAMP | No | If Shipper indicated delivery location opening hours format: `HH:MM` | schedule |\n| stop1_hours_end | TYPE | No | If Shipper indicated delivery location closing hours format: `HH:MM` | schedule |\n| stop1_notes | STRING | No | Additional delivery notes | schedule |\n| stop1_contact_name | STRING | MANDATORY | Name of contact person at delivery location | schedule |\n| stop1_contact_phone | STRING | MANDATORY | Phone number of contact person at delivery location | schedule |\n| stop1_contact_email | STRING | MANDATORY | Email of contact person at delivery location | schedule |\n| stop1_address_type | STRING | No | Can be `Address`, `Seaport` or `Airport` | schedule |\n\n##### Country values\n\nCountries can be provided as names, based on common American spelling for the territory, however it is recommended to provide either the 2 or 3 letter ISO 3166 code. \nA full list of ISO codes per country can be found here [Wikipedia link](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)\n\n##### State / province values\n\nAt this moment both pickup_state and stop1_state expect the common American full name spelling for the states. Pluto will be updated to also be able to consume common 2 letter acronyms for states in Mexico and the United States as well as Provinces in Canada. Other countries do not expect any such state at this moment.\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 201 | Created | \"Request created with Shipment number S71229654\" |\n| 403 | Forbidden | check Authentication token |\n\nIn case of a successful POST your response will contain the details that were posted, as confirmation. \n\n## Sample Request Body : \n```json\n{\n \"organization\": {\n \"location\": \"SL2963758\",\n \"quoting_deadline_date\": \"2022-03-25\",\n \"quoting_deadline_time\": \"12:00\",\n \"confirmation_date\": \"2022-03-30\",\n \"confirmation_time\": \"12:00\",\n \"custom_longfield_01\": \"My longfield input\",\n \"title\": \"1629256678058\",\n \"good_items\": [\n {\n \"handling_unit\": \"box\",\n \"units\": 1,\n \"length\": 60,\n \"height\": 60,\n \"width\": 60,\n \"m_unit\": \"cm\",\n \"weight\": 200,\n \"w_unit\": \"kg\",\n \"stackable\": false,\n \"hazardous\": false,\n \"is_dangerous_good\": false,\n \"additional_information\": \"TAKE CARE\",\n \"dangerous_good_value\": \"3\",\n \"container_type\": null,\n \"nmfc_class\": \"50\",\n \"good_customs_information\": [\n {\n \"value\": 8000,\n \"currency_code\": \"USD\",\n \"description\": \"Gear R\",\n \"hs_code\": \"E2\"\n }\n ]\n }\n ]\n },\n \"service\": {\n \"incoterm\": \"EXW\",\n \"insurance\": true,\n \"insurance_instructions\": \"AIA\",\n \"service_requirement\": \"DTD\",\n \"export_clearance\": \"3\",\n \"export_clearance_instructions\": \"NO\",\n \"transit_clearance\": \"1\",\n \"transit_clearance_instructions\": \"Sure\",\n \"import_clearance\": \"0\",\n \"import_clearance_instructions\": \"Checking\",\n \"air_charter_invited\": false,\n \"next_flight_invited\": false,\n \"ocean_freight_invited\": false,\n \"rail_freight_invited\": false,\n \"regular_air_freight_invited\": true,\n \"road_freight_invited\": false,\n \"road_freight_type\": \"\"\n },\n \"schedule\": {\n \"pickup_street\": \"CleanTech\",\n \"pickup_address_name\": \"01#03, STech\",\n \"pickup_state\": \"Singapore\",\n \"pickup_zipcode\": \"119932\",\n \"pickup_city\": \"Singapore\",\n \"pickup_country\": \"Singapore\",\n \"pickup_date\": \"2022-03-20\",\n \"pickup_time\": \"09:00:00\",\n \"pickup_contact_name\": \"ARTC\",\n \"pickup_contact_phone\": \"69095381\",\n \"pickup_contact_email\": \"artc@artc.a-star.edu.sg\",\n \"pickup_notes\": \"CHECK\",\n \"stop1_street\": \"Plot E261, Industrial Area, Sector 74 Phase 8B\",\n \"stop1_address_name\": \"56#87, SpeedWide\",\n \"stop1_state\": \"Punjab\",\n \"stop1_zipcode\": \"160071\",\n \"stop1_city\": \"Mohali\",\n \"stop1_country\": \"India\",\n \"stop1_date\": \"2022-04-01\",\n \"stop1_time\": \"09:00:00\",\n \"stop1_contact_name\": \"Arcstone Pte. Ltd.\",\n \"stop1_contact_phone\": \"69095381\",\n \"stop1_contact_email\": \"arcstone@arcstone.co\",\n \"stop1_notes\": \"CHECK\"\n }\n}\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": { "fullRequest": { "summary": "Create a full quote request", "value": { "organization": { "location": "SL2963758", "quoting_deadline_date": "2022-03-25", "quoting_deadline_time": "12:00", "confirmation_date": "2022-03-30", "confirmation_time": "12:00", "custom_longfield_01": "My longfield input", "title": "1629256678058", "good_items": [ { "handling_unit": "box", "units": 1, "length": 60, "height": 60, "width": 60, "m_unit": "cm", "weight": 200, "w_unit": "kg", "stackable": false, "hazardous": false, "is_dangerous_good": false, "additional_information": "TAKE CARE", "dangerous_good_value": "3", "container_type": null, "nmfc_class": "50", "good_customs_information": [ { "value": 8000, "currency_code": "USD", "description": "Gear R", "hs_code": "E2" } ] } ] }, "service": { "incoterm": "EXW", "insurance": true, "insurance_instructions": "AIA", "service_requirement": "DTD", "export_clearance": "3", "export_clearance_instructions": "NO", "transit_clearance": "1", "transit_clearance_instructions": "Sure", "import_clearance": "0", "import_clearance_instructions": "Checking", "air_charter_invited": false, "next_flight_invited": false, "ocean_freight_invited": false, "rail_freight_invited": false, "regular_air_freight_invited": true, "road_freight_invited": false, "road_freight_type": "" }, "schedule": { "pickup_street": "CleanTech", "pickup_address_name": "01#03, STech", "pickup_state": "Singapore", "pickup_zipcode": "119932", "pickup_city": "Singapore", "pickup_country": "Singapore", "pickup_date": "2022-03-20", "pickup_time": "09:00:00", "pickup_contact_name": "ARTC", "pickup_contact_phone": "69095381", "pickup_contact_email": "artc@artc.a-star.edu.sg", "pickup_notes": "CHECK", "stop1_street": "Plot E261, Industrial Area, Sector 74\r\n\r\nPhase 8B", "stop1_address_name": "56#87, SpeedWide", "stop1_state": "Punjab", "stop1_zipcode": "160071", "stop1_city": "Mohali", "stop1_country": "India", "stop1_date": "2022-04-01", "stop1_time": "09:00:00", "stop1_contact_name": "Arcstone Pte. Ltd.", "stop1_contact_phone": "69095381", "stop1_contact_email": "arcstone@arcstone.co", "stop1_notes": "CHECK" } } } } } } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Create Request" } }, "/api/1/requests/": { "get": { "tags": [ "Quote Requests" ], "summary": "List view", "description": "The Request List View end-point provides a list of Requests associated with the requesting user. \n\n## Request URI\n```\nGET https://pluto.cargobase.com/api/1/requests/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Status codes\n|\tStatus\t|\tDescription\t|\tResolution\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\t200\t|\tOK\t|\t--\t|\n|\t403\t|\tForbidden \t|\tcheck Authentication token, or status of the request\t|\n\n## Request Response definition\n\n### Results (Main message)\n|\tKey\t|\tValue\t|\tDefinition\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\tquote_request_reference\t|\tSTRING\t|\tCargobase Request ID\t|\n|\tquote_request_title\t|\tSTRING \t|\tTitle of the Request, as provided by the Shipper\t|\n|\tfreight_modes\t|\tSTRING \t|\tRequested freight modes, can be multiple for Shipper but single for Provider\t|\n|\tshipper\t|\tSTRING \t|\tName of the Shipper company\t|\n|\tquotes_count\t|\tINT \t|\tNumber of received quotes, in case of shipper or submitted quotes in case of Provider\t|\n|\tstatus\t|\tSTRING \t|\tCurrent status of request, see list for potential status below\t|\n|\tpickup_city\t|\tSTRING \t|\tThe city name for Shipment pickup\t|\n|\tpickup_country\t|\tSTRING \t|\tThe country name for Shipment pickup\t|\n|\tstop1_city\t|\tSTRING \t|\tThe city name for the requested delivery location\t|\n|\tstop1_country\t|\tSTRING \t|\tThe country name for the requested delivery location\t|\n|\tcreated_by\t|\tSTRING \t|\tThe email ID of the initiating user account, visible to Shippers only\t|\n|\tlast_modified\t|\tSTRING \t|\tThe Date and Time in UTC since the most recent update to this request\t|\n|\topen_for_quotation\t|\tBOOLEAN \t|\tTo indicate if quotes can still be submitted (PROVIDERS ONLY)\t|\n\n#### Request status options\n|\tStatus\t|\tDefinition\t|\n| \t---------\t| ----------------\t| \n|\tNew\t|\tAn active request that has not yet received quotes\t|\n|\tQuoted\t|\tAn active request that has received 1 or multiple quotes\t|\n|\tCanceled\t|\tA request that was canceled manually or automatically\t|\n|\tIn Progress\t|\t**Only for Providers** - displayed when quoting is ongoing, but the quote has not been submitted\t|\n\n\n### \"Footer\"\n|\tKey\t|\tValue\t|\tDefinition\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\tprevious\t|\tSTRING\t|\tURL to the previous page, in case page number is higher than 1\t|\n|\trecord_end\t|\tINTEGER \t|\tNumber of the highest request on the page\t|\n|\tcount\t|\tINTEGER \t|\tTotal number of requests available to the user, across all pages\t|\n|\tpage\t|\tINTEGER \t|\tPage number\t|\n|\trecord_start\t|\tINTEGER \t|\tNumber of the first request on the page\t|\n|\tnext\t|\tSTRING \t|\tURL to the previous page, in case page number is lower than the highest available\t|\n\n## Pagination\nThe request list results are paginated with 10 results per page by default.\nResults are displayed in descending order, that means that result 1 on page 1 is the newest addition. \nTo request a specific page append `?page=XX` to the URI. \nTo request a specific number of items per page, append `?page_size=xx` to the URI.\n\nResults can also be filtered to only display results of the account calling the API, this is done by appending '=self'.\n\n### Example\nCalling the API to show only your own requests, with 25 per page and viewing page 3 is\n```\nGET https://pluto.cargobase.com/api/1/requests/?=self&page_size=25&page=3\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Known issues\n* None at this moment", "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" } ], "responses": { "200": { "description": "OK", "headers": { "Date": { "schema": { "type": "string", "example": "Wed, 24 Apr 2019 06:44:32 GMT" } }, "Content-Type": { "schema": { "type": "string", "example": "application/json" } }, "Content-Length": { "schema": { "type": "integer", "example": "3337" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "x-amzn-RequestId": { "schema": { "type": "string", "example": "6a8b0236-665c-11e9-ab3e-61767f24d8e8" } }, "Strict-Transport-Security": { "schema": { "type": "string", "example": "max-age=63072000; includeSubdomains;" } }, "Allow": { "schema": { "type": "string", "example": "GET, HEAD, OPTIONS" } }, "x-amzn-Remapped-Content-Length": { "schema": { "type": "integer", "example": "3337" } }, "X-Frame-Options": { "schema": { "type": "string", "example": "SAMEORIGIN" } }, "Content-Language": { "schema": { "type": "string", "example": "courier-network-inc" } }, "x-amzn-Remapped-Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Set-Cookie": { "schema": { "type": "string", "example": "django_language=en; Path=/" } }, "x-amz-apigw-id": { "schema": { "type": "string", "example": "YoXYiF75vHcF8NQ=" } }, "Vary": { "schema": { "type": "string", "example": "Accept, Accept-Language, Origin, Cookie" } }, "x-amzn-Remapped-Server": { "schema": { "type": "string", "example": "nginx/1.10.3 (Ubuntu)" } }, "x-amzn-Remapped-Date": { "schema": { "type": "string", "example": "Wed, 24 Apr 2019 06:44:32 GMT" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "quote_request_reference": "S93345678", "quote_request_title": "Latest Request", "freight_modes": "On board courier (OBC)", "shipper": "Shipper Demo Inc", "quotes_count": 0, "status": "New", "pickup_city": "Changchun", "pickup_country": "China", "stop1_city": "Regensburg", "stop1_country": "Germany", "modified": "2021-05-21 06:42:14" }, { "quote_request_reference": "S92345678", "quote_request_title": "Second latest Request", "freight_modes": "Next flight out (NFO)", "shipper": "Shipper Demo Inc", "quotes_count": 1, "status": "Canceled", "pickup_city": "Taguig", "pickup_country": "Philippines", "stop1_city": "Cuautla", "stop1_country": "Mexico", "modified": "2021-05-21 04:39:12" }, { "quote_request_reference": "S82345678", "quote_request_title": "Third Latest Request", "freight_modes": "On board courier (OBC)", "shipper": "Shipper Demo Inc", "quotes_count": 1, "status": "Uninvited", "pickup_city": "Kumamoto", "pickup_country": "Japan", "stop1_city": "Babenhausen", "stop1_country": "Germany", "modified": "2021-05-21 02:14:01" }, { "quote_request_reference": "S72345678", "quote_request_title": "Fourth Latest Request", "freight_modes": "On board courier (OBC)", "shipper": "Shipper Demo Inc", "quotes_count": 1, "status": "New", "pickup_city": "Tlajomulco de Zuñiga, Jalisco, México.", "pickup_country": "Mexico", "stop1_city": "Bognor Regis", "stop1_country": "United Kingdom", "modified": "2021-05-21 01:47:34" }, { "quote_request_reference": "S62345678", "quote_request_title": "Fifth Latest Request", "freight_modes": "Road freight", "shipper": "Shipper Demo Inc", "quotes_count": 0, "status": "New", "pickup_city": "Puebla", "pickup_country": "Mexico", "stop1_city": "Puebla", "stop1_country": "Mexico", "modified": "2021-05-21 01:46:34" }, { "quote_request_reference": "S52345678", "quote_request_title": "Sixth Latest Request", "freight_modes": "On board courier (OBC)", "shipper": "Shipper Demo Inc", "quotes_count": 1, "status": "Quoted", "pickup_city": "Nogales", "pickup_country": "United States", "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.", "stop1_country": "Mexico", "modified": "2021-05-20 23:57:27" }, { "quote_request_reference": "S42345678", "quote_request_title": "Seventh Latest Request", "freight_modes": "Road freight", "shipper": "Shipper Demo Inc", "quotes_count": 0, "status": "Opened", "pickup_city": "Culiacan", "pickup_country": "Mexico", "stop1_city": "Ciudad Juarez", "stop1_country": "Mexico", "modified": "2021-05-20 23:55:11" }, { "quote_request_reference": "S32345678", "quote_request_title": "Eight Latest Request", "freight_modes": "On board courier (OBC), Next flight out (NFO)", "shipper": "Shipper Demo Inc", "quotes_count": 1, "status": "New", "pickup_city": "hangzhou, zhejiang", "pickup_country": "China", "stop1_city": "Santa Teresa", "stop1_country": "United States", "modified": "2021-05-20 22:29:41" }, { "quote_request_reference": "S22345678", "quote_request_title": "Nineth Latest Request", "freight_modes": "Road freight", "shipper": "Shipper Demo Inc", "quotes_count": 0, "status": "New", "pickup_city": "Santa Teresa", "pickup_country": "United States", "stop1_city": "Buchanan", "stop1_country": "United States", "modified": "2021-05-20 22:17:52" }, { "quote_request_reference": "S12345678", "quote_request_title": "Tenth Latest Request", "freight_modes": "On board courier (OBC)", "shipper": "Shipper Demo Inc", "quotes_count": 2, "status": "New", "pickup_city": "Xuhui", "pickup_country": "China", "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.", "stop1_country": "Mexico", "modified": "2021-05-20 21:53:29" } ], "previous": null, "record_end": 10, "count": 750, "page": 1, "record_start": 1, "next": "https://pluto.cargobase.com/api/1/requests/?page=2" } } } }, "default": { "description": "default", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "quote_request_reference": "S93345678", "quote_request_title": "Latest Request", "freight_modes": "On board courier (OBC)", "quotes_count": 0, "status": "New", "pickup_city": "Changchun", "pickup_country": "China", "stop1_city": "Regensburg", "stop1_country": "Germany", "created_by": "you@cargobase.com", "modified": "2021-05-21 06:42:14" }, { "quote_request_reference": "S92345678", "quote_request_title": "Second latest Request", "freight_modes": "Next flight out (NFO)", "quotes_count": 3, "status": "Quoted", "pickup_city": "Taguig", "pickup_country": "Philippines", "stop1_city": "Cuautla", "stop1_country": "Mexico", "created_by": "your_colleague@cargobase.com", "modified": "2021-05-21 04:39:12" }, { "quote_request_reference": "S82345678", "quote_request_title": "Third Latest Request", "freight_modes": "On board courier (OBC)", "quotes_count": 4, "status": "Quoted", "pickup_city": "Kumamoto", "pickup_country": "Japan", "stop1_city": "Babenhausen", "stop1_country": "Germany", "created_by": "your_ERP_solution@cargobase.com", "modified": "2021-05-21 02:14:01" }, { "quote_request_reference": "S72345678", "quote_request_title": "Fourth Latest Request", "freight_modes": "On board courier (OBC)", "quotes_count": 9, "status": "Quoted", "pickup_city": "Tlajomulco de Zuñiga, Jalisco, México.", "pickup_country": "Mexico", "stop1_city": "Bognor Regis", "stop1_country": "United Kingdom", "created_by": "you@cargobase.com", "modified": "2021-05-21 01:47:34" }, { "quote_request_reference": "S62345678", "quote_request_title": "Fifth Latest Request", "freight_modes": "Road freight", "quotes_count": 8, "status": "Quoted", "pickup_city": "Puebla", "pickup_country": "Mexico", "stop1_city": "Puebla", "stop1_country": "Mexico", "created_by": "you@cargobase.com", "modified": "2021-05-21 01:46:34" }, { "quote_request_reference": "S52345678", "quote_request_title": "Sixth Latest Request", "freight_modes": "On board courier (OBC)", "quotes_count": 4, "status": "Quoted", "pickup_city": "Nogales", "pickup_country": "United States", "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.", "stop1_country": "Mexico", "created_by": "someonelse@cargobase.com", "modified": "2021-05-20 23:57:27" }, { "quote_request_reference": "S42345678", "quote_request_title": "Seventh Latest Request", "freight_modes": "Road freight", "quotes_count": 6, "status": "Quoted", "pickup_city": "Culiacan", "pickup_country": "Mexico", "stop1_city": "Ciudad Juarez", "stop1_country": "Mexico", "created_by": "notme@cargobase.com", "modified": "2021-05-20 23:55:11" }, { "quote_request_reference": "S32345678", "quote_request_title": "Eight Latest Request", "freight_modes": "On board courier (OBC), Next flight out (NFO)", "quotes_count": 7, "status": "Quoted", "pickup_city": "hangzhou, zhejiang", "pickup_country": "China", "stop1_city": "Santa Teresa", "stop1_country": "United States", "created_by": "your_colleague@cargobase.com", "modified": "2021-05-20 22:29:41" }, { "quote_request_reference": "S22345678", "quote_request_title": "Nineth Latest Request", "freight_modes": "Road freight", "quotes_count": 1, "status": "Canceled", "pickup_city": "Santa Teresa", "pickup_country": "United States", "stop1_city": "Buchanan", "stop1_country": "United States", "created_by": "your_colleague@cargobase.com", "modified": "2021-05-20 22:17:52" }, { "quote_request_reference": "S12345678", "quote_request_title": "Tenth Latest Request", "freight_modes": "On board courier (OBC)", "quotes_count": 2, "status": "Canceled", "pickup_city": "Xuhui", "pickup_country": "China", "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.", "stop1_country": "Mexico", "created_by": "the_architect@cargobase.com", "modified": "2021-05-20 21:53:29" } ], "previous": null, "record_end": 10, "count": 175, "page": 1, "record_start": 1, "next": "https://pluto.cargobase.com/api/1/requests/?page=2" } } } } }, "x-displayName": "List view" } }, "/api/1/quotes/": { "post": { "tags": [ "Quote Requests" ], "summary": "Submit Quote", "description": "The Submit Quote end-point can be used to post Quotes on requests. This end-point is only available to providers. \nAdditionally, providers can only quote on requests they have been invited for.\n\n**Note** This end-point only applies to Providers \n**Note** Currently only Regular Air freight, NFO, OBC, Road and Ocean quotes are supported - additional freight modes will follow.\n\n## Request URI\n\n```\nPOST https://pluto.cargobase.com/api/1/quotes\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Known issues\n\n* None, at the moment. If you find anything; please reach out to [support@cargobase.com](mailto:support@cargobase.com)\n\n## Body message\n\nContents of the body message can be dependant on the freight mode that you are quoting on. \nAt this moment, only Air freight, NFO, OBC, Road and Ocean quotes are supported. Some fields are specific to the freight mode.\n\nThe example selector on this operation has a payload for each supported mode: Regular air freight, NFO, OBC, Road freight, and Ocean freight.\n\nThe message body is constructed around 4 main object categories and 2 subcategories. \nEach category is mandatory in the request, specific values are not.\n\n### Main object categories\n\n| Category parameter | Purpose | Child object |\n| --- | --- | --- |\n| organization | Shipment references, such as Shipment ID and provider team | none |\n| service | Details such as freight mode, quote title and other service characteristics | none |\n| financial | Generic financial details | cost_items, additional_cost_data |\n| schedule | Details such as expected pickup and delivery and quote validity | flights (optional) |\n\n#### organization values\n\n| Key | Type | Purpose | Availability |\n| --- | --- | --- | --- |\n| shipment_id | STRING | The shipment ID (S12345678) you are quoting on | Mandatory |\n| provider_team | STRING | The reference number (PT12345678) of the provider team associated with the quote | Mandatory |\n| quoted_by | STRING | E-mail address of the quotee - this has to be an activa Cargobase account | Mandatory |\n\n**Note** You can only reference a provider team that is invited on this quote. The available teams are different per request. The 'provider_reference' list in the 'Service'-object in the Request Detail api response contains available teams for that shipment.\n\n#### service values\n\n| Key | Type | Purpose | Availability |\n| --- | --- | --- | --- |\n| freight_mode | STRING | The freight mode associated with the quote - see values below | Mandatory |\n| max_weight | FLOAT | The maximum weight the Courier can travel with | Mandatory, OBC ONLY |\n| max_weight_UOM | STRING | KG or LBS for the max_weight value | Mandatory, OBC ONLY |\n| max_dimension | FLOAT | The maximum dimension of the Courier can travel with | Mandatory, Road Freight ONLY |\n| max_dimension_UOM | STRING | meter or feet for the max_dimension value | Mandatory, Road Freight ONLY |\n| road_freight_type | STRING | Freight type for the courier, see below for the availale road freight types | Mandatory, Road Freight ONLY |\n| vessel_number | STRING | Vessel Number of the ship | Mandatory, Ocean Freight ONLY |\n| vessel_info | JSON | Can hold new vessel info like vessel_name, vessel_operator_carrier_code , carrier_voyage_number. | Mandatory, Ocean Freight ONLY |\n| chargeable_weight | FLOAT | Chargeable weight of air freight and NFO Quotes | Mandatory, for air freight & NFO |\n| weight_UOM | STRING | KG or LBS for the chargeable_weight value | Mandatory, for air freight & NFO |\n| quote_title | STRING | Title of your quote, to distinguish in case of multiple quotes | Mandatory |\n| primary_tracking_number | STRING | Your internal reference, or future tracking number | Mandatory |\n##### road_freight_type values\n\n| Road Freight mode | API string |\n| --- | --- |\n| Full Truck Load | ftl |\n| Less than Truck Load | ltl |\n| Ground Expedite | ge |\n| Specialized - Car haulers, flat-beds, dump truck | spe |\n| Multi stop | multi-stop |\n| Multi drop | multi-drop |\n##### freight_mode values\n\n| Freight mode | API string | Comment |\n| --- | --- | --- |\n| On board courier (OBC) | OBC | Available now |\n| Next flight out (NFO) | NFO | Available now |\n| Regular air freight | Regular air freight | Available now |\n| Air charter | Charter | 1.1+ |\n| Parcel | n.a. | Will not be supported |\n| Road freight | Road freight | Available now |\n| Ocean freight | Ocean freight | Available now |\n| Rail freight | Rail | 1.1+ |\n\n#### financial values\n\n| Key | Type | Purpose | Availability |\n| --- | --- | --- | --- |\n| quote_currency | ISO 4217:2015 STRING | Currency of all cost items in your quote | Mandatory |\n| not_included | STRING | Description of quote scope boundaries | Mandatory |\n| cost_details | OBJECT | Specific mandatory cost items | Mandatory |\n\n##### cost_details values\n\n| Key | Type | Purpose | Availability |\n| --- | --- | --- | --- |\n| quoted_amount | DECIMAL | OBC/Road/Ocean base fee | Mandatory, OBC/Road/Ocean ONLY |\n| total_excess_cost | DECIMAL | Optional excess cost | Optional, OBC ONLY |\n| air_freight_charges | DECIMAL | Regular Air and NFO per kg/lbs fee | Mandatory, for air freight & NFO |\n| additional_cost_data | OBJECT | Optional additional cost items | Optional |\n\n###### additional_cost_data values\n\n| Key | Type | Purpose | Availability |\n| --- | --- | --- | --- |\n| additional_cost_description | STRING | Description of additional cost item | Conditional |\n| additional_cost_item_amount | DECIMAL | Amount of the additional cost item | Conditional |\n\n**Note** Multiple additional cost items can be added - as dictionary objects within `additional_cost_data`\n\n#### schedule values\n\n| Key | Type | Purpose | Availability |\n| --- | --- | --- | --- |\n| expected_pickup_date | STRING | Expected pickup date, format `YYYY-MM-DD` | Mandatory |\n| expected_pickup_time | STRING | Expected pickup time, format `HH:MM` | Mandatory |\n| expected_stop1_date | STRING | Expected delivery date, format `YYYY-MM-DD` | Mandatory |\n| expected_stop1_time | STRING | Expected delivery time, format `HH:MM` | Mandatory |\n| quote_valid_until_date | STRING | Quote validity date, format `YYYY-MM-DD` | Mandatory |\n| quote_valid_until_time | STRING | Quote validity time, format `HH:MM`
**Note** Time is in line with personal preferences - contact Support to request changes | Mandatory |\n| vessel_departure_date | STRING | Vessel departure date, format `YYYY-MM-DD` | Mandatory Ocean Freight Only |\n| vessel_arrival_date | STRING | Vessel arrival date, format `YYYY-MM-DD` | Mandatory Ocean Freight Only |\n| flights | ARRAY of OBJECT | One or more commercial flight details (optional) | Optional |\n\n##### flights values\n\nThe flights object is an array of objects pertaining to commercial flights. The array is optional, but can contain 1 or more flights. \nSince this is an array, ensure to enclose the individual flight objects in brackets, like this `[{OBJECT}, {OBJECT}]`\n\n| Key | Type | Purpose | Availability |\n| --- | --- | --- | --- |\n| airline_code | STRING | 2 Character IATA code of the airline | Mandatory |\n| flight_number | STRING | Number / reference of the flight, as a string | Mandatory |\n| departure_date | STRING | Date as YYYY-MM-DD | Mandatory |\n| departure_time | STRING | Time as HH:MM | Mandatory |\n| departure_airport_code | STRING | IATA code of departure airport | Mandatory |\n| arrival_date | STRING | Date as YYYY-MM-DD | Mandatory |\n| arrival_time | STRING | Time as HH:MM | Mandatory |\n| arrival_airport_code | STRING | IATA code of arrival airport | Mandatory |\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 201 | Created | Your quote has been posted |\n| 403 | Forbidden | Check Authentication token |\n\nIn case of a successful POST your response will contain the Quote reference number (QR12345678).\n", "requestBody": { "required": true, "description": "Pick an example for the freight mode you are quoting. Each payload includes the shared objects plus the fields that mode requires.", "content": { "application/json": { "schema": { "type": "object", "description": "Quote body. `organization`, `service`, `financial`, and `schedule` are always sent. Mode-specific keys are listed on the operation and shown in the examples.", "additionalProperties": true }, "examples": { "regularAirFreight": { "summary": "Regular air freight", "description": "Air and NFO quotes require chargeable weight and air_freight_charges. flights is optional.", "value": { "organization": { "provider_team": "PT12345678", "quoted_by": "quotes@example.com", "shipment_id": "S12345678" }, "service": { "freight_mode": "Regular air freight", "quote_title": "Regular air freight quote", "primary_tracking_number": "REF-1001", "chargeable_weight": 120, "weight_UOM": "kg" }, "financial": { "quote_currency": "USD", "not_included": "Destination charges and customs clearance are excluded.", "cost_details": { "air_freight_charges": 4.5, "additional_cost_data": [ { "additional_cost_description": "Fuel surcharge", "additional_cost_item_amount": 85 } ] } }, "schedule": { "expected_pickup_date": "2026-10-08", "expected_pickup_time": "09:00", "expected_stop1_date": "2026-10-12", "expected_stop1_time": "16:00", "quote_valid_until_date": "2026-10-06", "quote_valid_until_time": "17:00", "flights": [ { "airline_code": "LH", "flight_number": "400", "departure_date": "2026-10-09", "departure_time": "10:20", "departure_airport_code": "FRA", "arrival_date": "2026-10-10", "arrival_time": "13:05", "arrival_airport_code": "SIN" } ] } } }, "nfo": { "summary": "Next flight out (NFO)", "description": "Same charge fields as regular air freight, with freight_mode NFO.", "value": { "organization": { "provider_team": "PT12345678", "quoted_by": "quotes@example.com", "shipment_id": "S12345678" }, "service": { "freight_mode": "NFO", "quote_title": "NFO quote", "primary_tracking_number": "REF-1001", "chargeable_weight": 35, "weight_UOM": "kg" }, "financial": { "quote_currency": "USD", "not_included": "Destination charges and customs clearance are excluded.", "cost_details": { "air_freight_charges": 19.01 } }, "schedule": { "expected_pickup_date": "2026-10-08", "expected_pickup_time": "09:00", "expected_stop1_date": "2026-10-12", "expected_stop1_time": "16:00", "quote_valid_until_date": "2026-10-06", "quote_valid_until_time": "17:00", "flights": [ { "airline_code": "LH", "flight_number": "400", "departure_date": "2026-10-09", "departure_time": "10:20", "departure_airport_code": "FRA", "arrival_date": "2026-10-10", "arrival_time": "13:05", "arrival_airport_code": "SIN" } ] } } }, "obc": { "summary": "On board courier (OBC)", "description": "OBC requires max weight and a quoted_amount. total_excess_cost is optional.", "value": { "organization": { "provider_team": "PT12345678", "quoted_by": "quotes@example.com", "shipment_id": "S12345678" }, "service": { "freight_mode": "OBC", "quote_title": "OBC quote", "primary_tracking_number": "REF-1001", "max_weight": 15, "max_weight_UOM": "kg" }, "financial": { "quote_currency": "USD", "not_included": "Destination charges and customs clearance are excluded.", "cost_details": { "quoted_amount": 2400, "total_excess_cost": 150 } }, "schedule": { "expected_pickup_date": "2026-10-08", "expected_pickup_time": "09:00", "expected_stop1_date": "2026-10-12", "expected_stop1_time": "16:00", "quote_valid_until_date": "2026-10-06", "quote_valid_until_time": "17:00" } } }, "roadFreight": { "summary": "Road freight", "description": "Road requires max dimension, a road_freight_type, and quoted_amount.", "value": { "organization": { "provider_team": "PT12345678", "quoted_by": "quotes@example.com", "shipment_id": "S12345678" }, "service": { "freight_mode": "Road freight", "quote_title": "Road freight quote", "primary_tracking_number": "REF-1001", "max_dimension": 2.4, "max_dimension_UOM": "meter", "road_freight_type": "ftl" }, "financial": { "quote_currency": "USD", "not_included": "Destination charges and customs clearance are excluded.", "cost_details": { "quoted_amount": 1800 } }, "schedule": { "expected_pickup_date": "2026-10-08", "expected_pickup_time": "09:00", "expected_stop1_date": "2026-10-12", "expected_stop1_time": "16:00", "quote_valid_until_date": "2026-10-06", "quote_valid_until_time": "17:00" } } }, "oceanFreight": { "summary": "Ocean freight", "description": "Ocean requires vessel number, vessel_info, quoted_amount, and vessel departure and arrival dates.", "value": { "organization": { "provider_team": "PT12345678", "quoted_by": "quotes@example.com", "shipment_id": "S12345678" }, "service": { "freight_mode": "Ocean freight", "quote_title": "Ocean freight quote", "primary_tracking_number": "REF-1001", "vessel_number": "IMO 9395044", "vessel_info": { "vessel_name": "Example Vessel", "vessel_operator_carrier_code": "MAEU", "carrier_voyage_number": "412E" } }, "financial": { "quote_currency": "USD", "not_included": "Destination charges and customs clearance are excluded.", "cost_details": { "quoted_amount": 3200 } }, "schedule": { "expected_pickup_date": "2026-10-08", "expected_pickup_time": "09:00", "expected_stop1_date": "2026-10-12", "expected_stop1_time": "16:00", "quote_valid_until_date": "2026-10-06", "quote_valid_until_time": "17:00", "vessel_departure_date": "2026-10-09", "vessel_arrival_date": "2026-10-28" } } } } } } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Submit Quote" }, "get": { "tags": [ "Quote Requests" ], "summary": "Quotes List", "description": "The Quote List end-point can be used to retrieve a list of quotes submitted by you for a given shipment.\n\n## Request URI\n```\nGET https://pluto.cargobase.com/api/1/quotes?shipment=S12345678\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Query Parameter\n| Key | Value |\n| --------- | ---------------- |\n| shipment | \"S12345678\" - the shipment ID |\n\n## Known issues\n* None, at the moment. If you find anything; please reach out to support@cargobase.com\n\n## Status codes\n| Status | Description | Resolution |\n| --------- | ---------------- | ---------------- |\n| 200 | OK | n.a. |\n| 403 | Forbidden | check Authentication token |\n\nIn case of a successful POST your response will contain the details that were posted, as confirmation.\n\n\n## Sample response\n\n```\n{\n \"count\": 3,\n \"next\": null,\n \"previous\": null,\n \"page\": 1,\n \"record_start\": 1,\n \"record_end\": 3,\n \"results\": [\n {\n \"shipment_reference\": \"S12346578\",\n \"quote_reference\": \"Q56641234\",\n \"provider_reference\": \"PT12344874\",\n \"provider_team_name\": \"AIR NA - EU\",\n \"freight_mode\": \"Regular air freight\",\n \"quote_title\": \"Air Consolidated\",\n \"total_quoted_amount\": 8237.0,\n \"total_quoted_currency\": \"USD\",\n \"status\": \"Submitted\",\n \"pickup_city\": \"Toronto\",\n \"pickup_country\": \"Canada\",\n \"stop1_country\": \"France\",\n \"stop1_city\": \"Limoges\",\n \"primary_tracking_number\": \"T1981204\"\n },\n {\n \"shipment_reference\": \"S87654321\",\n \"quote_reference\": \"Q01110110\",\n \"provider_reference\": \"PT12344874\",\n \"provider_team_name\": \"AIR NA - EU\",\n \"freight_mode\": \"Next flight out (NFO)\",\n \"quote_title\": \"Air Express\",\n \"total_quoted_amount\": 15450.0,\n \"total_quoted_currency\": \"USD\",\n \"status\": \"Submitted\",\n \"pickup_city\": \"Toronto\",\n \"pickup_country\": \"Canada\",\n \"stop1_country\": \"France\",\n \"stop1_city\": \"Limoges\",\n \"primary_tracking_number\": \"\"\n },\n {\n \"shipment_reference\": \"S18273645\",\n \"quote_reference\": \"Q13336587\",\n \"provider_reference\": \"PT36478645\",\n \"provider_team_name\": \"Ocean NA - EU\",\n \"freight_mode\": \"Ocean freight\",\n \"quote_title\": \"Ocean PtP\",\n \"total_quoted_amount\": 4135.0,\n \"total_quoted_currency\": \"USD\",\n \"status\": \"Submitted\",\n \"pickup_city\": \"Toronto\",\n \"pickup_country\": \"Canada\",\n \"stop1_country\": \"France\",\n \"stop1_city\": \"Limoges\",\n \"primary_tracking_number\": \"\"\n }\n ]\n}\n```", "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "shipment", "in": "query", "schema": { "type": "string" }, "description": "Replace S12345678 with the shipment ID.", "example": "S12345678" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Quotes List" } }, "/api/1/shipments/": { "get": { "tags": [ "Shipments" ], "summary": "List view", "description": "The Shipment List View end-point provides a list of Shipments associated with the requesting user. \n\n## Request URI\n```\nGET https://pluto.cargobase.com/api/1/shipments/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n**Note** Shipments that have not yet been awarded are considered 'Requests' and are not yet available in this list.\n\n## Status codes\n|\tStatus\t|\tDescription\t|\tResolution\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\t200\t|\tOK\t|\t--\t|\n|\t403\t|\tForbidden \t|\tcheck Authentication token, or status of the Shipment\t|\n\n## Request Response definition\n\n### Results (Main message)\n|\tKey\t|\tValue\t|\tDefinition\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\tshipment_reference\t|\tSTRING\t|\tCargobase Shipment ID\t|\n|\tshipment_title\t|\tSTRING \t|\tTitle of the Shipment, as provided by the Shipper\t|\n|\tfreight_mode\t|\tSTRING \t|\tAwarded Freight Mode\t|\n|\tshipper\t|\tSTRING \t|\tName of the Shipper company\t|\n|\tquote_title\t|\tINT \t|\tTitle of the awarded quote\t|\n|\tstatus\t|\tSTRING \t|\tCurrent status of the shipment, see list for potential status below\t|\n|\tpickup_city\t|\tSTRING \t|\tThe city name for Shipment pickup\t|\n|\tpickup_country\t|\tSTRING \t|\tThe country name for Shipment pickup\t|\n|\tstop1_city\t|\tSTRING \t|\tThe city name of the Delivery location\t|\n|\tstop1_country\t|\tSTRING \t|\tThe country name of the Delivery location\t|\n|\tprimary_tracking_number\t|\tSTRING \t|\tThe Primary tracking / reference number of the Provider for this shipment\t|\n|\tcreated_by\t|\tSTRING \t|\tThe email ID of the initiating user account, visible to Shippers only\t|\n|\tlast_modified\t|\tSTRING \t|\tThe Date and Time in UTC since the most recent update to this shipment\t|\n\n#### Shipment status options\n|\tStatus\t|\tDefinition\t|\n| \t---------\t| ----------------\t| \n|\tBooked\t|\tAn awarded Shipment with a future pick-up time\t|\n|\tIn Transit\t|\tA Shipment with a past pick-up time and future delivery time\t|\n|\tDelayed\t|\tA non-delivered Shipment with a past delivery time\t|\n|\tCanceled\t|\tA Shipment that has been canceled by the Shipper < 24 hours ago\t|\n|\tDelivered\t|\tA Shipment that has been delivered < 24 hours\t|\n\n**Note** Shipments that are delivered or canceled will be removed from this list after 24 hours.\n\n### \"Footer\"\n|\tKey\t|\tValue\t|\tDefinition\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\tprevious\t|\tSTRING\t|\tURL to the previous page, in case page number is higher than 1\t|\n|\trecord_end\t|\tINTEGER \t|\tNumber of the highest Shipment on the page\t|\n|\tcount\t|\tINTEGER \t|\tTotal number of Shipments available to the user, across all pages\t|\n|\tpage\t|\tINTEGER \t|\tPage number\t|\n|\trecord_start\t|\tINTEGER \t|\tNumber of the first Shipment on the page\t|\n|\tnext\t|\tSTRING \t|\tURL to the previous page, in case page number is lower than the highest available\t|\n\n## Pagination\nThe Shipment list results are paginated with 10 results per page by default.\nResults are displayed in descending order, that means that result 1 on page 1 is the newest addition. \nTo request a specific page append `?page=XX` to the URI. \nTo request a specific number of items per page, append `?page_size=xx` to the URI.\n\n\nResults can also be filtered to only display results of the account calling the API, this is done by appending '=self'.\n\n### Example\nCalling the API to show only your own requests, with 25 per page and viewing page 3 is\n```\nGET https://pluto.cargobase.com/api/1/shipments/?=self&page_size=25&page=3\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Known issues\n* None at this moment.", "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" } ], "responses": { "200": { "description": "OK", "headers": { "Date": { "schema": { "type": "string", "example": "Wed, 24 Apr 2019 06:44:32 GMT" } }, "Content-Type": { "schema": { "type": "string", "example": "application/json" } }, "Content-Length": { "schema": { "type": "integer", "example": "3337" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "x-amzn-RequestId": { "schema": { "type": "string", "example": "6a8b0236-665c-11e9-ab3e-61767f24d8e8" } }, "Strict-Transport-Security": { "schema": { "type": "string", "example": "max-age=63072000; includeSubdomains;" } }, "Allow": { "schema": { "type": "string", "example": "GET, HEAD, OPTIONS" } }, "x-amzn-Remapped-Content-Length": { "schema": { "type": "integer", "example": "3337" } }, "X-Frame-Options": { "schema": { "type": "string", "example": "SAMEORIGIN" } }, "Content-Language": { "schema": { "type": "string", "example": "courier-network-inc" } }, "x-amzn-Remapped-Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Set-Cookie": { "schema": { "type": "string", "example": "django_language=en; Path=/" } }, "x-amz-apigw-id": { "schema": { "type": "string", "example": "YoXYiF75vHcF8NQ=" } }, "Vary": { "schema": { "type": "string", "example": "Accept, Accept-Language, Origin, Cookie" } }, "x-amzn-Remapped-Server": { "schema": { "type": "string", "example": "nginx/1.10.3 (Ubuntu)" } }, "x-amzn-Remapped-Date": { "schema": { "type": "string", "example": "Wed, 24 Apr 2019 06:44:32 GMT" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "shipment_reference": "S93345678", "shipment_title": "Latest Request", "freight_mode": "On board courier (OBC)", "primary_tracking": "", "status": "Booked", "pickup_city": "Changchun", "pickup_country": "China", "stop1_city": "Regensburg", "stop1_country": "Germany", "modified": "2021-05-21 06:42:14" }, { "shipment_reference": "S92345678", "shipment_title": "Second latest Request", "freight_mode": "Next flight out (NFO)", "primary_tracking": "CR20130224", "status": "Booked", "pickup_city": "Taguig", "pickup_country": "Philippines", "stop1_city": "Cuautla", "stop1_country": "Mexico", "modified": "2021-05-21 04:39:12" }, { "shipment_reference": "S82345678", "shipment_title": "Third Latest Request", "freight_mode": "On board courier (OBC)", "primary_tracking": "", "status": "Booked", "pickup_city": "Kumamoto", "pickup_country": "Japan", "stop1_city": "Babenhausen", "stop1_country": "Germany", "modified": "2021-05-21 02:14:01" }, { "shipment_reference": "S72345678", "shipment_title": "Fourth Latest Request", "freight_mode": "On board courier (OBC)", "primary_tracking": "2105211440", "status": "In Transit", "pickup_city": "Tlajomulco de Zuñiga, Jalisco, México.", "pickup_country": "Mexico", "stop1_city": "Bognor Regis", "stop1_country": "United Kingdom", "modified": "2021-05-21 01:47:34" }, { "shipment_reference": "S62345678", "shipment_title": "Fifth Latest Request", "freight_mode": "Road freight", "primary_tracking": "", "status": "In Transit", "pickup_city": "Puebla", "pickup_country": "Mexico", "stop1_city": "Puebla", "stop1_country": "Mexico", "modified": "2021-05-21 01:46:34" }, { "shipment_reference": "S52345678", "shipment_title": "Sixth Latest Request", "freight_mode": "On board courier (OBC)", "primary_tracking": "A113", "status": "In Transit", "pickup_city": "Nogales", "pickup_country": "United States", "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.", "stop1_country": "Mexico", "modified": "2021-05-20 23:57:27" }, { "shipment_reference": "S42345678", "shipment_title": "Seventh Latest Request", "freight_mode": "Road freight", "primary_tracking": "T1000-AS", "status": "In Transit", "pickup_city": "Culiacan", "pickup_country": "Mexico", "stop1_city": "Ciudad Juarez", "stop1_country": "Mexico", "modified": "2021-05-20 23:55:11" }, { "shipment_reference": "S32345678", "shipment_title": "Eight Latest Request", "freight_mode": "On board courier (OBC), Next flight out (NFO)", "primary_tracking": "429106", "status": "Delayed", "pickup_city": "hangzhou, zhejiang", "pickup_country": "China", "stop1_city": "Santa Teresa", "stop1_country": "United States", "modified": "2021-05-20 22:29:41" }, { "shipment_reference": "S22345678", "shipment_title": "Nineth Latest Request", "freight_mode": "Road freight", "primary_tracking": "493389", "status": "Delayed", "pickup_city": "Santa Teresa", "pickup_country": "United States", "stop1_city": "Buchanan", "stop1_country": "United States", "modified": "2021-05-20 22:17:52" }, { "shipment_reference": "S12345678", "shipment_title": "Tenth Latest Request", "freight_mode": "On board courier (OBC)", "primary_tracking": "19840412", "status": "Incomplete", "pickup_city": "Xuhui", "pickup_country": "China", "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.", "stop1_country": "Mexico", "modified": "2021-05-20 21:53:29" } ], "previous": null, "record_end": 10, "count": 175, "page": 1, "record_start": 1, "next": "https://pluto.cargobase.com/api/1/shipments/?page=2" } } } } }, "x-displayName": "List view" } }, "/api/1/invoices/": { "get": { "tags": [ "Invoices" ], "summary": "List view", "description": "The Invoices List View end-point provides a list of Invoices associated with the requesting user. \n\n## Request URI\n```\nGET https://pluto.cargobase.com/api/1/invoices/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Status codes\n|\tStatus\t|\tDescription\t|\tResolution\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\t200\t|\tOK\t|\t--\t|\n|\t403\t|\tForbidden \t|\tcheck Authentication token\t|\n\n## Request Response definition\n### Results (Main message)\n|\tKey\t|\tValue\t|\tDefinition\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\tshipment_reference\t|\tSTRING\t|\tCargobase Shipment ID\t|\n|\tinvoice_reference\t|\tSTRING \t|\tTitle of the Shipment, as provided by the Shipper\t|\n|\tinvoice_status\t|\tSTRING \t|\tCurrent status of the shipment, see list for potential status below\t|\n|\tprovider_name\t|\tSTRING \t|\tName of the provider / Freight forwarder submitting the invoice\t|\n|\tprovider_invoice_number\t|\tSTRING \t|\tA provider submitted invoice reference\t|\n|\tfreight_mode\t|\tSTRING \t|\tAwarded Freight Mode\t|\n|\tprimary_tracking_number\t|\tSTRING \t|\tThe HAWB or main tracking number of the shipment\t|\n|\tsubmit_date\t|\tSTRING \t|\tThe initial date the invoice was submitted\t|\n|\tmodified\t|\tSTRING \t|\tThe Date and Time in UTC since the most recent update to this invoice\t|\n\n#### Invoice status options\n|\tStatus\t|\tDefinition\t|\n| \t---------\t| ----------------\t| \n|\tAwaiting audit\t|\tAn invoice that has been submitted, but is awaiting audit approval\t|\n|\tApproved\t|\tAn invoice that was approved\t|\n|\tDeclined\t|\tAn invoice that was declined, and can be resubmitted by the provider\t|\n|\tRemoved\t|\tAn invoice that will not be submitted\t|\n|\tCanceled\t|\tAn invoice that was submitted, but retracted by the provider\t|\n|\tUnsubmitted\t|\tAn new or draft invoice (Visible to providers only)\t|\n\n### \"Footer\"\n|\tKey\t|\tValue\t|\tDefinition\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\tprevious\t|\tSTRING\t|\tURL to the previous page, in case page number is higher than 1\t|\n|\trecord_end\t|\tINTEGER \t|\tNumber of the oldest invoice on the page\t|\n|\tcount\t|\tINTEGER \t|\tTotal number of Invoices available to the user, across all pages\t|\n|\tpage\t|\tINTEGER \t|\tPage number\t|\n|\trecord_start\t|\tINTEGER \t|\tNumber of the first Invoice on the page\t|\n|\tnext\t|\tSTRING \t|\tURL to the previous page, in case page number is lower than the highest available\t|\n\n## Pagination & Filters\n### Filter by date\nInvoices can be listed based on their specific submission date, or by the current or previous month.\nFuture updates will include more extensive filter options.\nTo filter based on a specific date, append =submit_date=YYYY-MM-DD\nTo filter based on last month, append =submit_date=last_month\nTo filter based on this month, append =submit_date=this_month\n\n### Filter by status\nInvoices can be listed based on their specific status, to do so the api call should include status=[status_value]\n#### Status values\n|\tStatus\t|\tValue\t|\tDefinition\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\tAwaiting audit\t|\tawaiting_audit\t|\tAn invoice that has been submitted, but is awaiting audit approval\t|\n|\tApproved\t|\tapproved\t|\tAn invoice that was approved\t|\n|\tDeclined\t|\tdeclined\t|\tAn invoice that was declined, and can be resubmitted by the provider\t|\n|\tRemoved\t|\tremoved\t|\tAn invoice that will not be submitted\t|\n|\tCanceled\t|\tcanceled\t|\tAn invoice that was submitted, but retracted by the provider\t|\n|\tUnsubmitted\t|\tunsubmitted\t|\tAn new or draft invoice (Visible to providers only)\t\t|\n\n### Pagination\nThe Invoice list results are paginated with 50 results per page by default.\nResults are displayed in descending order, that means that result 1 on page 1 is the newest addition. \nTo request a specific page append `?page=XX` to the URI. \nTo request a specific number of items per page, append `?page_size=xx` to the URI.\n\n### Example\nCalling the API to show only approved invoices from last month\n```\nGET https://pluto.cargobase.com/api/1/invoices/?status=approved&submit_date=last_month\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Known issues\n* None at this moment.", "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "submit_date:ASC", "submit_date:DESC" ] }, "description": "Sort invoices by submission date. Use `submit_date:ASC` for oldest first, or `submit_date:DESC` for newest first." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "List view" } }, "/api/1/invoices/{invoice_reference}": { "get": { "tags": [ "Invoices" ], "summary": "Details", "description": "The Invoice Detail end-point can be used to retrieve all specifics of an invoice.\nPlease be aware; some shipments do have multiple invoices.\n\n## Request URI\n```\nGET https://pluto.cargobase.com/api/1/invoices/`INVOICE_REFERENCE`\nAuthorization: Token your_token_here\n```\n\n## Status codes\n|\tStatus\t|\tDescription\t|\tResolution\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\t200\t|\tOK\t|\t--\t|\n|\t403\t|\tForbidden \t|\tcheck Authentication token, or status of the Invoice\t|\n|\t404\t|\tNot Found \t|\tCheck the Invoice reference\t|\n\n## Request Response\n\n### Invoice Response categories\nThe response is divided into 4 possible categories for shippers and providers, these are:\n\n|\tCategory\t|\tDefinition\t|\n| \t---------\t| ----------------\t| \n|\torganization\t|\tDetails related to the organization, such as WBS Codes or Cost Centers\t|\n|\tservice\t|\tDetails related to the service, such as freight mode, incoterms or clearance instructions\t|\n|\tschedule\t|\tDetails related to pickup & delivery timing and locations\t|\n|\tfinancial\t|\tData related to the invoice itself and the quoted amount\t|\n|\tattachments\t|\tList of files related to the invoice, such as invoice PDFs or supporting documents\t|\n\n#### Invoice > attachments\nList of attachments associated with the invoice.\n\n|\tKey\t |\tValue\t |\tDescription\t |\n|------------------|---------|-----------------------------------------------------------|\n|\tid\t |\tINTEGER |\tInternal identifier of the attachment |\n|\tname\t |\tSTRING\t |\tFile name of the attachment |\n|\treference_number|\tSTRING\t |\tReference number for the attachment |\n|\tfile_extension\t|\tSTRING\t |\tFile extension (e.g., `pdf`, `jpg`) |\n|\turl\t |\tSTRING\t |\tPath to the file location, typically under `/media/` |\n\n\n#### Invoice > organization\nDetails related to the organization, such as WBS Codes or Cost Centers.\n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\tshipment_id\t|\tSTRING\t|\tThe request ID\t|\n|\tinvoice_reference\t|\tSTRING\t|\tThe unique identifier of the invoice, generated by Cargobase\t|\n|\tprovider_invoice_number\t|\tSTRING\t|\tIdentifier of the invoie, submitted by the provider\t|\n|\tinvoice_status\t|\tSTRING\t|\tCurrent status of the invoice, see list for potentiatl status below\t|\n|\tinvoice_submit_date\t|\tSTRING\t|\tDate the invoice was submitted\t|\n|\tapproved_by\t|\tSTRING\t|\tName of the invoice approver \t|\n|\tapproved_by_email\t|\tSTRING\t|\tEmail of the invoice approver\t|\n|\tshipment_title\t|\tSTRING\t|\tTitle of the shipment\t|\n|\tinvoice_location\t|\tSTRING\t|\tOrganizational unit in Cargobase to which the invoice is assigned\t|\n|\tcost_center\t|\tSTRING\t\t|\tValue entered in the cost_center field, the shipper might use a custom label for this field and therefore not recognise the term `cost_center`\t|\n|\tcustom_field1\t|\tSTRING\t\t|\tValue entered in the custom_field1 field, the shipper might use a custom label for this field and therefore not recognise the term `custom_field`\t|\n|\treason_code\t|\tSTRING\t\t|\tValue entered in the reason_code field, the shipper might use a custom label for this field and therefore not recognise the term `reason_code`\t|\n|\tbilled_from_name\t|\tSTRING\t|\tAddressee of the invoicer\t|\n|\tbilled_from_address\t|\tOBJECT\t|\tObject containing address details of the sender\t|\n|\tbilled_to_name\t|\tSTRING\t|\tAddressee of the recipient\t|\n|\tbilled_to_address\t|\tOBJECT\t|\tObject containing address details of the recipient\t|\n|\ttotal_invoices\t|\tINTEGER\t|\tNumber of invoices associated with the shipment\t|\n|\tgood_items\t|\tOBJECT\t|\tDetails related to the packing list\t|\n\n#### invoice_status options\n\n|\tStatus\t|\tDefinition\t|\n| \t---------\t| ----------------\t| \n|\tUnsubmitted\t|\tA draft invoice, visible to Providers only\t|\n|\tAwaiting Audit\t|\tSubmitted by the provider and now awaiting approval/declination by the shipper \t|\n|\tApproved\t|\tAn invoice that was approved and forwarder to the correct payment provider\t|\n|\tDeclined\t|\tAn invoice that was declined and will need to be resubmitted\t|\n|\tCanceled\t|\tAn invoice that was canceled by the provider before receiving approval\t|\n|\tRemoved\t|\tAn invoice that was removed from contention by the provider, and will not be submitted for approval or payment\t|\n|\tAuto removed\t|\tAn invoie that was automatically removed by the provider and will not be submitted for approval or payment\t|\n\n\n#### Invoice > organization > good_items\nDetails related to the packing list. The good_items object contains limited information related to the actual packing list. Details regarding the 'requested' packing list, can be recovered from the request detail end-point. \n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\trequested_total_weight\t|\tFLOAT\t|\tValue of the total weight of the packing list, as defined by the shipper during the quote request \t|\n|\trequested_total_weight_uom\t|\tSTRING\t|\tUnit of Measurement for the total requested weight (either KG or LBS) \t|\n|\tactual_total_weight\t|\tFLOAT\t|\tValue of the total weight of the packing list, as moved and defined by the provider, e.g. the weight the invoice is based on \t|\n|\tactual_total_weight_uom\t|\tSTRING\t|\tUnit of Measurement for the total actual weight (either KG or LBS) \t|\n|\trequest_units\t|\tINTEGER\t|\tNumber of individual items requested to move \t|\n|\tactual_units\t|\tINTEGER\t|\tNumber of individual items actually moved \t|\n|\tactual_good_items\t|\tOBJECT\t|\tObject with details on individual handling units. \t|\n\n##### Invoice > organization > good_items > actual_good_items\nDetails related to the packing list. The good_items object contains limited information related to the actual packing list. Details regarding the 'requested' packing list, can be recovered from the request detail end-point. \n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\thandling_unit\t|\tSTRING\t|\tName or identifier of the handling unit (e.g. \"box\" or \"pallet\") \t|\n|\tlength\t|\tFLOAT\t|\tNumber relating to the dimension of the longest horizontal axis \t|\n|\theight\t|\tFLOAT\t|\tNumber relating to the dimension of the vertical axis \t|\n|\twidth\t|\tFLOAT\t|\tNumebr relating to the dimension of the shortest horizontal axis\t|\n|\tm_unit\t|\tSTRING\t|\tRelated to dimensional unit of measurement, either CM or INCH \t|\n|\tweight\t|\tFLOAT\t|\tNumber related to the weight of an individual item \t|\n|\tw_unit\t|\tSTRING\t|\tUnit of Measurement for the total requested weight (either KG or LBS) \t|\n|\ttotal_cbm\t|\tFLOAT\t|\tNumber related to the cumuliative cubic meters of handling units of this type \t|\n|\tunit_cbm\t|\tFLOAT\t|\tNumber related to the cubic meters of an individual handling unit of this type \t|\n|\tstackable\t|\tBOOLEAN\t|\tBoolean to indicate if you can put one of this on top of the other \t|\n|\thazardous\t|\tBOOLEAN\t|\tBooelan to indicate if the contents are considered hazardous (Subjective ranking) \t|\n|\tis_dangerous_good\t|\tBOOLEAN\t|\tBoolean to indicate if contents are classified in one of 9 dangerous goods categories (Objective classification) \t|\n|\tdangerous_good_value\t|\tINTEGER\t|\tNumber relating to the Dangerous goods category (1 through 9) \t|\n|\tcrating_required\t|\tBOOLEAN\t|\tBoolean to indicate if crating of the item is requested \t|\n|\tcrating_required_by_date\t|\tSTRING\t|\tEnd date by when the crating should be completed before pickup, date in YYYY-MM-DD \t|\n|\tother_instructions\t|\tSTRING\t|\tText from a custom instruction field \t|\n|\tadditional_information\t|\tSTRING\t|\tText from a general 'additional information' textarea, can include line break tags `
` \t|\n|\tcontainer_type\t|\tSTRING\t|\tText refering to the type of container (see Shipment or request details for detailed description) \t|\n|\tgood_customs_information\t|\tOBJECT\t|\tObject related to manually added customs details (see Shipment or request details for detailed description) \t|\n\n#### Invoice > service\nBasic information related to the service, such as requested freight mode and incoterms.\n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\tincoterm\t|\tSTRING\t|\tThe requested incoterm\t|\n|\tfreight_mode\t|\tSTRING\t|\tThe freight mode of the shipment - see freight mode options below\t|\n|\tprovider\t|\tSTRING\t|\tName of the awarded party\t|\n|\tquote_id\t|\tSTRING\t|\tReference number of the selected quote\t|\n|\tprovider_reference\t|\tSTRING\t|\tOptional reference to the provider\t|\n\n##### freight_mode values\n* Air charter\n* Next flight out (NFO)\n* Ocean freight\n* Rail freight\n* Regular air freight\n* Road freight\n* Parcel\n* On board courier (OBC)\n* Custom values, specific to each shipper.\n\n#### Invoice > schedule\nDetails related to pickup & delivery timing and locations.\n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\tpickup_airport_code\t|\tSTRING\t|\tIATA Airport code, if identified otherwise `null`\t|\n|\tpickup_airport\t|\tSTRING\t|\tAirport Name, if identified otherwise `null`\t|\n|\tpickup_seaport_code\t|\tSTRING\t|\tSeaport code, if identified otherwise `null`\t|\n|\tpickup_seaport\t|\tTYPE\t|\tSeaport name, if identified otherwise `null`\t|\n|\tpickup_street\t|\tSTRING\t| Pickup street address\t|\n|\tpickup_address_name\t|\tSTRING\t|\tPickup company name\t| \n|\tpickup_state\t|\tSTRING\t|\tThe pickup State in case of US or Mexico\t|\n|\tpickup_zipcode\t|\tSTRING\t|\tThe pickup postal code \t|\n|\tpickup_city\t|\tSTRING\t| The pickup city\t|\n|\tpickup_country\t|\tSTRING\t| The pickup country\t|\n|\tquoted_pickup_date\t|\tTIMESTAMP\t|\tQuoted pickup date, format `YYYY-MM-DD`\t| \n|\tquoted_pickup_time\t|\tTIMESTAMP\t|\tQuoted pickup time, format `HH:MM`\n|\tactual_pickup_date\t|\tTIMESTAMP\t|\tQuoted or Updated Pickup date. \t|\n|\tactual_pickup_time\t|\tTIMESTAMP\t|\tQuoted or Updated Pickup time.\t|\n|\tpickup_timezone\t|\tSTRING\t|\tTimezone name \t| \n|\tpickup_notes\t|\tSTRING\t|\tAdditional pickup notes \t|\n|\tpickup_contact_name\t|\tSTRING\t|\tName of contact person at pickup location \t| \n|\tpickup_contact_phone\t|\tSTRING\t|\tPhone number of contact person at pickup location \t| \n|\tpickup_contact_email\t|\tSTRING\t|\tEmail of contact person at pickup location \t| \n|\tpickup_address_type\t|\tSTRING\t|\tCan be `Address`, `Seaport` or `Airport` \t| \n|\tstop1_airport\t|\tSTRING\t|\tAirport Name, if identified otherwise `null`\t|\n|\tstop1_seaport_code\t|\tSTRING\t|\tSeaport code, if identified otherwise `null`\t|\n|\tstop1_seaport\t|\tTYPE\t|\tSeaport name, if identified otherwise `null`\t|\n|\tstop1_street\t|\tSTRING\t| Delivery street address\t|\n|\tstop1_address_name\t|\tSTRING\t|\tDelivery company name\t| \n|\tstop1_state\t|\tSTRING\t|\tThe delivery State in case of US or Mexico\t|\n|\tstop1_zipcode\t|\tSTRING\t|\tThe delivery postal code \t|\n|\tstop1_city\t|\tSTRING\t| The delivery city\t|\n|\tstop1_country\t|\tSTRING\t| The delivery country\t|\n|\tstop1_quoted_delivery_date\t|\tTIMESTAMP\t|\tQuoted delivery date, format `YYYY-MM-DD`\t| \n|\tstop1_quoted_delivery_time\t|\tTIMESTAMP\t|\tQuoted deliverytime, format `HH:MM`\n|\tstop1_actual_delivery_date\t|\tTIMESTAMP\t|\tQuoted or Updated delivery date. \t|\n|\tstop1_actual_delivery_time\t|\tTIMESTAMP\t|\tQuoted or Updated delivery time.\t|\n|\tstop1_notes\t|\tSTRING\t|\tAdditional delivery notes \t|\n|\tstop1_contact_name\t|\tSTRING\t|\tName of contact person at delivery location \t| \n|\tstop1_contact_phone\t|\tSTRING\t|\tPhone number of contact person at delivery location \t| \n|\tstop1_contact_email\t|\tSTRING\t|\tEmail of contact person at delivery location \t| \n|\tstop1_address_type\t|\tSTRING\t|\tCan be `Address`, `Seaport` or `Airport` \t| \n|\tpod_date\t|\tSTRING\t|\tDate of delivery \t| \n|\tpod_signed_by\t|\tSTRING\t|\tName of person who signed for the POD \t| \n\n#### Invoice > financial\nCustoms details per good item. This category is a child of a handling unit within category `Good items`.\n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\tcurrency |\tSTRING\t| Currency of the invoice \t|\n|\tquoted_amount |\tFLOAT\t| Amount of the original quote, before moving the shipment \t|\n|\tamount_due |\tFLOAT\t| Amount to be paid, for this invoice \t|\n|\ttotal_invoiced_amount |\tFLOAT\t| Total amount of all invoices for this shipment (Will be different from amount_due in case of multiple invoices)\t|\n|\tcost_details |\tOBJECT\t| Array with individual line items \t|\n\n\n##### Invoice > financial > cost_details\nDetails related to the line items of the invoice. \n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\ttitle\t|\tSTRING\t|\tName of the line item, can be a financial item or other classifier \t|\n|\tvalue\t|\tSTRING\t|\tString refering to a financial number, or in other case related to weight \t|\n|\tUOM\t|\tSTRING\t|\tIn case of a weight related line item, can be either \"KG\" or \"LBS\" \t|\n|\tcurrency\t|\tSTRING\t|\tIn case of a financial line item, will be the common 3 letter currency acronym \t|\n|\tsub_title\t|\tSTRING\t|\tSome additional information, mostly for weighted charges, e.g. '4 USD per Kg' \t|\n\n\n## Known issues\n* None at the moment", "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "invoice_reference", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Replace 'I12345678' with the actual invoice_reference", "example": "i12345678" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Details" } }, "/api/1/invoice-status-update/{invoice_reference}": { "post": { "tags": [ "Invoices" ], "summary": "Update Status", "description": "Use this endpoint to approve or decline an invoice.\n\n## Request URI\n```\nPOST https://pluto.cargobase.com/api/1/invoice-status-update/{invoice_reference}\nContent-Type: application/json\nAuthorization: Token your_token_here\n```", "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "invoice_reference", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique invoice reference identifier", "example": "I12345678" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approved", "declined" ], "description": "The action to apply to the invoice" }, "comment": { "type": "string", "description": "Comment explaining the reason for action" } }, "required": [ "action", "comment" ] }, "examples": { "approved": { "summary": "Approve", "value": { "action": "approved", "comment": "Matches the awarded quote." } }, "declined": { "summary": "Decline", "value": { "action": "declined", "comment": "Amount does not match the awarded quote." } } } } } }, "responses": { "201": { "description": "Status updated successfully", "content": { "application/json": { "example": { "success": true, "details": { "action": "declined", "comment": "Shubh is rejecting" } } } } }, "400": { "description": "Invalid request or invoice already acted upon", "content": { "application/json": { "example": { "message": "The invoice is already Approved/Declined." } } } }, "403": { "description": "Forbidden (invalid token or permission issue)" }, "404": { "description": "Invoice not found" } }, "x-displayName": "Update Status" } }, "/api/1/quickrequests/{qr_reference}/": { "get": { "tags": [ "Quick Requests" ], "summary": "Quick Request Detail", "description": "The Quick Request Detail end-point can be used to retrieve all specifics of a Quick request.\nA Quick Request is a 'draft' version of a Quote request, therefore this end-point is only available to shippers.\n\n## Request URI\n```\nGET https://pluto.cargobase.com/api/1/quickrequests/`Quick_request_reference`\nAuthorization: Token your_token_here\n```\n\n## Status codes\n|\tStatus\t|\tDescription\t|\tResolution\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\t200\t|\tOK\t|\t--\t|\n|\t403\t|\tForbidden \t|\tcheck Authentication token, or status of the quick request\t|\n\n## Request Response\n\n### Request Response categories\nThe response is divided into 3 possible categories for shippers, these are:\n\n|\tCategory\t|\tDefinition\t|\n| \t---------\t| ----------------\t| \n|\torganization\t|\tDetails related to the organization, such as WBS Codes or Cost Centers\t|\n|\trelated_request\t|\tInformation about a related shipment, after the quick request is converted into a quote request\t|\n|\tschedule\t|\tDetails related to pickup & delivery timing and locations\t|\n\n#### Request Response: Organization\nDetails related to the organization, such as WBS Codes or Cost Centers.\n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\tquick_request_reference\t|\tSTRING\t|\tThe reference number unique to this quick request\t|\n|\tquick_request_title\t|\tSTRING\t\t|\tTitle of the Quick Request, as provided by the Shipper\t|\n|\tpayment_location\t|\tSTRING\t\t|\tThe name of the organizational unit in Cargobase responsible for handling this request\t|\n|\tinvoice_location\t|\tSTRING\t\t|\tThe name of the organizational unit in Cargobase to which the provider will submit their invoice(s)\t|\n|\tquick_request_creation_date\t|\tDATE\t|\tCreation date of the Quick request, YYYY-MM-DD \t|\n|\tquick_request_creation_time\t|\tTIME\t|\tTime of day of creation of the Quick request, HH:MM:SS \t|\n|\tquick_request_status\t|\tSTRING\t|\tCurrent status of the quick request, see list for potential status below \t|\n|\tquick_request_created_by_name\t|\tSTRING\t|\tName of the creator of the Quick Request \t|\n|\tquick_request_created_by_email\t|\tSTRING\t|\tEmail of the creator of the Quick Request \t|\n|\tCustom_field1...\t|\tSTRING\t|\tOne or more strings related to custom 'organizational fields' specific to a shipper, such as 'Reason code' or 'WBS Code' \t|\n\n#### Request status options\n|\tStatus\t|\tDefinition\t|\n| \t---------\t| ----------------\t| \n|\tPending\t|\tA new quick request, that has not been converted into a quote request.\t|\n|\tProcessing\t|\tA quick request that has been converted into a quote request\t|\n|\tShipping\t|\tA quick request that has lead to a booked shipment\t|\n|\tArchived\t|\tA quick request that has been delivered or is canceled\t|\n\n#### Request Response: Related Request\nInformation about a related shipment, after the quick request is converted into a quote request.\n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\trelated_request_id\t|\tSTRING\t|\tThe reference number of the Quote request / Shipment\t|\n|\trelated_request_status\t|\tSTRING\t|\tStatus of the Quote request / Shipment\t|\n|\trelated_request_creation_date\t|\tDATE\t|\tThe date when the Quick request was created into a Quote request, YYYY-MM-DD\t|\n|\trelated_request_creation_time\t|\tTIME\t|\tThe time of day when the Quick request was created into a Quote request, HH:MM:SS\t|\n|\trelated_request_created_by_name\t|\tSTRING\t|\tName of the convertor of the Quick Request\t|\n|\trelated_request_created_by_email\t|\tSTRING\t|\tEmail of the convertor of the Quick Request\t|\n|\trelated_request_quotes_received\t|\tINTEGER\t|\tThe number of quotes received on the resulting Quote Request\t|\n\n\n#### Request Response: Schedule\nDetails related to pickup & delivery timing and locations.\n\n|\tKey\t|\tValue\t|\tDescription\t|\n| \t---------\t| ----------------\t| ----------------\t| \n|\tpickup_airport_code\t|\tSTRING\t|\tIATA Airport code, if identified otherwise `null`\t|\n|\tpickup_airport\t|\tSTRING\t|\tAirport Name, if identified otherwise `null`\t|\n|\tpickup_seaport_code\t|\tSTRING\t|\tSeaport code, if identified otherwise `null`\t|\n|\tpickup_seaport\t|\tTYPE\t|\tSeaport name, if identified otherwise `null`\t|\n|\tpickup_street\t|\tSTRING\t| Pickup street address\t|\n|\tpickup_address_name\t|\tSTRING\t|\tPickup company name\t| \n|\tpickup_state\t|\tSTRING\t|\tThe pickup State in case of US or Mexico\t|\n|\tpickup_zipcode\t|\tSTRING\t|\tThe pickup postal code \t|\n|\tpickup_city\t|\tSTRING\t| The pickup city\t|\n|\tpickup_country\t|\tSTRING\t| The pickup country\t|\n|\tpickup_date\t|\tTIMESTAMP\t|\tRequested pickup date, format `YYYY-MM-DD`\t| \n|\tpickup_time\t|\tTIMESTAMP\t|\tRequested pickup time, format `HH:MM`\n|\tpickup_time_type\t|\tINTEGER\t|\tRequested pickup type can be `1=Regular`or `2=Between`\t|\n|\tpickup_end_date\t|\tTIMESTAMP\t|\tRequested pickup end date, in case of pickup_time_type 2\t| \n|\tpickup_end_time\t|\tTIMESTAMP\t|\tRequested pickup end time, in case of pickup_time_type 2\t|\n|\tpickup_hours_start\t|\tTIMESTAMP\t|\tIf Shipper indicated pickup location opening hours format: `HH:MM` \t|\n|\tpickup_hours_end\t|\tTYPE\t|\tIf Shipper indicated pickup location closing hours format: `HH:MM`\t|\n|\tpickup_timezone\t|\tSTRING\t|\tTimezone name \t| \n|\tpickup_notes\t|\tSTRING\t|\tAdditional pickup notes \t|\n|\tpickup_contact_name\t|\tSTRING\t|\tName of contact person at pickup location \t| \n|\tpickup_contact_phone\t|\tSTRING\t|\tPhone number of contact person at pickup location \t| \n|\tpickup_contact_email\t|\tSTRING\t|\tEmail of contact person at pickup location \t| \n|\tpickup_address_type\t|\tSTRING\t|\tCan be `Address`, `Seaport` or `Airport` \t| \n|\tstop1_airport\t|\tSTRING\t|\tAirport Name, if identified otherwise `null`\t|\n|\tstop1_seaport_code\t|\tSTRING\t|\tSeaport code, if identified otherwise `null`\t|\n|\tstop1_seaport\t|\tTYPE\t|\tSeaport name, if identified otherwise `null`\t|\n|\tstop1_street\t|\tSTRING\t| Delivery street address\t|\n|\tstop1_address_name\t|\tSTRING\t|\tDelivery company name\t| \n|\tstop1_state\t|\tSTRING\t|\tThe delivery State in case of US or Mexico\t|\n|\tstop1_zipcode\t|\tSTRING\t|\tThe delivery postal code \t|\n|\tstop1_city\t|\tSTRING\t| The delivery city\t|\n|\tstop1_country\t|\tSTRING\t| The delivery country\t|\n|\tstop1_date\t|\tTIMESTAMP\t|\tRequested delivery date, format `YYYY-MM-DD`\t| \n|\tstop1_time\t|\tTIMESTAMP\t|\tRequested delivery time, format `HH:MM`\n|\tstop1_time_type\t|\tINTEGER\t|\tRequested delivery type can be `1=Regular`or `2=Between`\t|\n|\tstop1_end_date\t|\tTIMESTAMP\t|\tRequested delivery end date, in case of stop1_time_type 2\t| \n|\tstop1_end_time\t|\tTIMESTAMP\t|\tRequested delivery end time, in case of stop1_time_type 2\t|\n|\tstop1_hours_start\t|\tTIMESTAMP\t|\tIf Shipper indicated delivery location opening hours format: `HH:MM` \t|\n|\tstop1_hours_end\t|\tTYPE\t|\tIf Shipper indicated delivery location closing hours format: `HH:MM`\t|\n|\tstop1_timezone\t|\tSTRING\t|\tTimezone name \t| \n|\tstop1_notes\t|\tSTRING\t|\tAdditional delivery notes \t|\n|\tstop1_contact_name\t|\tSTRING\t|\tName of contact person at delivery location \t| \n|\tstop1_contact_phone\t|\tSTRING\t|\tPhone number of contact person at delivery location \t| \n|\tstop1_contact_email\t|\tSTRING\t|\tEmail of contact person at delivery location \t| \n|\tstop1_address_type\t|\tSTRING\t|\tCan be `Address`, `Seaport` or `Airport` \t|", "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "qr_reference", "in": "path", "schema": { "type": "string", "pattern": "^QR[-\\d]+$" }, "required": true, "description": "Quick request reference number (e.g. `QR12345678`).", "example": "QR12345678" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Quick Request Detail" } }, "/api/1/requests/{shipment_reference}/": { "put": { "tags": [ "Quote Requests" ], "summary": "Update Request", "description": "The Request CREATE end-point can be used to generate quote requests on Cargobase, but also to update minor details on that request. This is useful, if you rely on your internal order/shipping platform to create requests in Cargobase. The options for updating your requests via API are purposefully rather limited at this moment. Any changes to allow more updates are not foreseen until an additional feature request is made. \n\nAt this moment, the PUT action can only be used to update Pickup notes, Delivery Notes or Additional Comments. This end-point can also be used to Cancel any open Quote request. Cancelation cannot be performed after a request has been booked.\n\n**Note** This end-point only applies to Shippers\n\n## Request URI\n```\nPUT https://pluto.cargobase.com/api/1/requests/create/S12345678\nContent-Type: application/json\nAuthentication: Token 'your_token_here'\n```\n\n## Body message\nThe body message is constructed around the same main object categories which are used to create the inital request. However, since only a few fields can be updated, only 2 categories apply. All values are optional, except when canceling a request; in that case there are 3 related key/value pairs that need to be shared. Each main object category should not be included if there are no updates for that category.\n\n### Main object categories\n|\tCategory parameter\t|\tPurpose\t|\n| \t-----------------\t| -------------\t|\n|\torganization\t|\tTo cancel the request, or update additional Comments\t|\n|\tservice\t|\tTo update pickup or delivery notes\t|\n\n#### organization values \n|\tKey\t|\tValue\t|\tMandatory\t|\tPurpose\t|\tParent object\t|\n| \t-----------------\t|\t-------------\t|\t-------------\t|\t-------------\t|\t-------------\t|\n|\tadditional_comments \t| STRING\t| OPTIONAL\t|\tA general remark on the overall request\t|\torganization \t|\n|\trequest_status \t|\tSTRING\t| OPTIONAL\t|\tCan only be used to cancel a request, value: 'canceled'\t|\torganization \t|\n|\tcancel_reason \t|\tINTEGER\t| CONDITIONAL\t|\tAn integer to select a predetermined cancel reason category, use only in combination with request_status\t|\torganization \t|\n|\tcancel_comment \t|\tSTRING\t| OPTIONAL\t|\tCan be used to share additional feedback to the provider, use only in combination with request_status\t|\torganization \t|\n\n##### cancel_reason values\nThese preselected reasons can be shared with the invited providers. \n\n|\tValue\t|\tDescription\t|\n| \t-----------------\t|\t-------------\t|\n|\t1\t|\tQuote(s) did not meet requirements\t|\n|\t2\t|\tQuote(s) were too expensive\t|\n|\t3\t|\tNo quotes received on time\t|\n|\t4\t|\tShipment not required anymore\t|\n|\t5\t|\tShipment booked from alternative source\t|\n|\t6\t|\tOther\t|\n\n#### schedule values \n|\tKey\t|\tValue\t|\tMandatory\t|\tPurpose\t|\tParent object\t|\n| \t-----------------\t|\t-------------\t|\t-------------\t|\t-------------\t|\t-------------\t|\n|\tpickup_notes\t|\tSTRING\t|\tNo\t|\tAdditional pickup notes \t|\tschedule\t|\n|\tstop1_notes\t|\tSTRING\t|\tNo\t|\tAdditional delivery notes \t|\tschedule\t|\n\n## Status codes\n|\tStatus\t|\tDescription\t|\tResolution\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\t201\t|\tCreated\t|\t\"Success : true\"\t|\n|\t403\t|\tForbidden \t|\tcheck Authentication token\t|\n\nIn case of a successful POST your response will contain the details that were posted, as confirmation.\n\n## Sample Request Body: \n\n ```json\n{\n \"organization\": {\n \"additional_comments\": \"Please quote both your fastest and your most economical option.\",\n \"request_status\": \"canceled\",\n \"cancel_reason\": 1,\n \"cancel_comment\": \"This quote request will be canceled, in favor of a larger request coming tomorrow.\"\n },\n \"schedule\": {\n \"pickup_notes\": \"Please park at loading bay 3, watch out for the Garden Gnome when turning in.\",\n \"stop1_notes\": \"Make sure to ring twice\"\n }\n}\n```", "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "examples": { "updateRequest": { "summary": "Update request", "value": { "organization": { "additional_comments": "Please quote both your fastest and your most economical option.", "request_status": "canceled", "cancel_reason": 1, "cancel_comment": "This quote request will be canceled, in favor of a larger request coming tomorrow." }, "schedule": { "pickup_notes": "Please park at loading bay 3, watch out for the Garden Gnome when turning in.", "stop1_notes": "Make sure to ring twice" } } } } } } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "shipment_reference", "in": "path", "schema": { "type": "string", "pattern": "^S[-\\d]+$" }, "required": true, "example": "S12345678", "description": "Shipment reference number (e.g. `S12345678`)." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Update Request" }, "get": { "tags": [ "Quote Requests" ], "summary": "Request Detail", "description": "The Request Detail end-point can be used to retrieve all specifics of a request. \nAfter a request has been awarded, the details can still be viewed, however: the Shipment Detail end-point should be approached for up to date data.\n\n## Request URI\n\n```\nGET https://pluto.cargobase.com/api/1/requests/`SHIPMENT_ID`\nAuthorization: Token your_token_here\n\n```\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | OK | \\-- |\n| 403 | Forbidden | check Authentication token, or status of the request |\n\n## Request Response\n\n### Request Response categories\n\nThe response is divided into 7 possible categories for shippers and 6 for providers, these are:\n\n| Category | Definition |\n| --- | --- |\n| organization | Details related to the organization, such as WBS Codes or Cost Centers |\n| service | Details related to the service, such as requested freight modes, incoterms or clearance instructions |\n| schedule | Details related to pickup & delivery timing and locations |\n| good_items | Details related to the packing list |\n| good_customs_information | Customs details per good item |\n| special_requirements | Specific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most. |\n| Quotes | **Only visible for Shippers** - Details regarding the quotes that have been received. |\n\n#### Request Response: Organization\n\nDetails related to the organization, such as WBS Codes or Cost Centers.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| shipment_id | STRING | The request ID |\n| requestor | STRUBG | The name of the person that created this request |\n| shipper | STRUBG | The name of the Company that initiated this request |\n| request_creation_datetime | TIMESTAMP | Format **YYYY-MM-DD HH:MM:SS** |\n| request_status | STRING | Current status of request, see list for potential status below |\n| title | STRING | Title of the Request, as provided by the Shipper |\n| cost_center | STRING | Value entered in the cost_center field, the shipper might use a custom label for this field and therefore not recognise the term `cost_center` |\n| custom_field1 | STRING | Value entered in the custom_field1 field, the shipper might use a custom label for this field and therefore not recognise the term `custom_field` |\n| reason_code | STRING | Value entered in the reason_code field, the shipper might use a custom label for this field and therefore not recognise the term `reason_code` |\n| goods_confirmation_type | STRING | Details related to the status of the packing list, only available to some. Status can be `Estimated` or `Finalised` |\n| good_items | GROUP | Packing list with details |\n| special_requirements | GROUP | Specific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most. |\n| additional_comments | STRING | Additional comments added by the shipper to the request |\n| dates&timers | SKIPPED | A set of days, hours, minutes and dates related to quoting or confirmation timers. See known issues. |\n| quotes | GROUP | **Only visible for Shippers** - Details regarding the quotes that have been received. |\n\n#### Request status options\n\n| Status | Definition |\n| --- | --- |\n| New | An active request that has not yet received quotes |\n| Quoted | An active request that has received 1 or multiple quotes |\n| Canceled | A request that was canceled manually or automatically |\n| In Progress | **Only for Providers** - displayed when quoting is ongoing, but the quote has not been submitted |\n\n#### Request Response: Service\n\nDetails related to the service, such as requested freight modes, incoterms or clearance instructions.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| incoterm | STRING | The requested incoterm |\n| delivery_service_level | INTEGER | Number of days associated with Service level, not available for most |\n| export_clearance | STRING | Indicator if Export clearance is requested, and what kind |\n| export_clearance_instructions | STRING | Instructions related to Export clearance |\n| transit_clearance | STRING | Indicator if Transit clearance is requested, and what kind |\n| transit_clearance_instructions | STRING | Instructions related to Transit clearance |\n| import_clearance | STRING | Indicator if Import clearance is requested, and what kind |\n| import_clearance_instructions | STRING | Instructions related to Import clearance |\n| insurance | BOOLEAN | Indicator to see if the provider is requested to arrange shipment insurance |\n| insurance_instructions | STRING | Instructions related to a positive insurance request |\n| service_requirement | STRING | Related to Door-to-Door, Door-to-Port, Port-to-Door or Port-to-Port but abbreviated in a TLA |\n| air_charter_invited | BOOLEAN | Boolean to see if this freight mode is invited |\n| next_flight_invited | BOOLEAN | Boolean to see if this freight mode is invited |\n| ocean_freight_invited | BOOLEAN | Boolean to see if this freight mode is invited |\n| rail_freight_invited | BOOLEAN | Boolean to see if this freight mode is invited |\n| regular_air_freight_invited | BOOLEAN | Boolean to see if this freight mode is invited |\n| road_freight_invited | BOOLEAN | Boolean to see if this freight mode is invited |\n| road_freight_type | STRING | Additional detail about road freight if road_freight_invited=TRUE |\n| provider_reference | STRING | A list of invited provider teams - Visible for Providers only |\n| available_teams | OBJECT | An object with 1 or multiple available teams that the request can be assigned to - Visible for Providers only |\n\n#### Request Response: Schedule\n\nDetails related to pickup & delivery timing and locations.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| pickup_airport_code | STRING | IATA Airport code, if identified otherwise `null` |\n| pickup_airport | STRING | Airport Name, if identified otherwise `null` |\n| pickup_seaport_code | STRING | Seaport code, if identified otherwise `null` |\n| pickup_seaport | TYPE | Seaport name, if identified otherwise `null` |\n| pickup_street | STRING | Pickup street address |\n| pickup_address_name | STRING | Pickup company name |\n| pickup_state | STRING | The pickup State in case of US or Mexico |\n| pickup_zipcode | STRING | The pickup postal code |\n| pickup_city | STRING | The pickup city |\n| pickup_country | STRING | The pickup country |\n| pickup_date | TIMESTAMP | Requested pickup date, format `YYYY-MM-DD` |\n| pickup_time | TIMESTAMP | Requested pickup time, format `HH:MM` |\n| pickup_time_type | INTEGER | Requested pickup type can be `1=Regular`or `2=Between` |\n| pickup_end_date | TIMESTAMP | Requested pickup end date, in case of pickup_time_type 2 |\n| pickup_end_time | TIMESTAMP | Requested pickup end time, in case of pickup_time_type 2 |\n| pickup_hours_start | TIMESTAMP | If Shipper indicated pickup location opening hours format: `HH:MM` |\n| pickup_hours_end | TYPE | If Shipper indicated pickup location closing hours format: `HH:MM` |\n| pickup_timezone | STRING | Timezone name |\n| pickup_notes | STRING | Additional pickup notes |\n| pickup_contact_name | STRING | Name of contact person at pickup location |\n| pickup_contact_phone | STRING | Phone number of contact person at pickup location |\n| pickup_contact_email | STRING | Email of contact person at pickup location |\n| pickup_address_type | STRING | Can be `Address`, `Seaport` or `Airport` |\n| stop1_airport | STRING | Airport Name, if identified otherwise `null` |\n| stop1_seaport_code | STRING | Seaport code, if identified otherwise `null` |\n| stop1_seaport | TYPE | Seaport name, if identified otherwise `null` |\n| stop1_street | STRING | Delivery street address |\n| stop1_address_name | STRING | Delivery company name |\n| stop1_state | STRING | The delivery State in case of US or Mexico |\n| stop1_zipcode | STRING | The delivery postal code |\n| stop1_city | STRING | The delivery city |\n| stop1_country | STRING | The delivery country |\n| stop1_date | TIMESTAMP | Requested delivery date, format `YYYY-MM-DD` |\n| stop1_time | TIMESTAMP | Requested delivery time, format `HH:MM` |\n| stop1_time_type | INTEGER | Requested delivery type can be `1=Regular`or `2=Between` |\n| stop1_end_date | TIMESTAMP | Requested delivery end date, in case of stop1_time_type 2 |\n| stop1_end_time | TIMESTAMP | Requested delivery end time, in case of stop1_time_type 2 |\n| stop1_hours_start | TIMESTAMP | If Shipper indicated delivery location opening hours format: `HH:MM` |\n| stop1_hours_end | TYPE | If Shipper indicated delivery location closing hours format: `HH:MM` |\n| stop1_timezone | STRING | Timezone name |\n| stop1_notes | STRING | Additional delivery notes |\n| stop1_contact_name | STRING | Name of contact person at delivery location |\n| stop1_contact_phone | STRING | Phone number of contact person at delivery location |\n| stop1_contact_email | STRING | Email of contact person at delivery location |\n| stop1_address_type | STRING | Can be `Address`, `Seaport` or `Airport` |\n\n#### Request Response: Good items\n\nDetails related to the packing list. This category is a child of `Organization`. \nThese values are grouped per handling unit, each shipment can have multiple handling units. \nEach shipment can also have multiple handling units of the same type, but differences in dimensions, notes or classifications.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| units | INTEGER | Number of this type of handling unit |\n| handling_unit | STRING | Handling unit type |\n| length | DOUBLE | Length value |\n| height | DOUBLE | Height value |\n| width | DOUBLE | Width value |\n| m_unit | STRING | LxWxH unit of measurement, can be `cm` or `inch` |\n| weight | INTEGER | Weight of individual handling unit piece, should be multiple by number of units for total Weight |\n| w_unit | STRING | Weight unit of measurement, can be `kg` or `lbs` |\n| stackable | BOOLEAN | Indicator if individual piece can be stacked |\n| hazardous | BOOLEAN | Indicator if goods are considered hazardous |\n| crating_required | BOOLEAN | Indicator if the provider is requested to provide crating, will be `null` for most |\n| crating_required_by_date | TIMESTAMP | Date & Time of final possibility to provide crating services, will be `null` for most |\n| is_dangerous_good | BOOLEAN | Indicator if contents are classified as a Dangerous good |\n| dangerous_good_value | INTEGER | Indicator of DG Category |\n| other_instructions | STRING | Description in case of handling unit `other` |\n| additional_information | STRING | Additional instructions related to these goods |\n| container_type | STRING | Description of container type, in case of handling unit `container` (e.g. 20Ft standard) |\n| refrigerated_container | BOOLEAN | Indicator if container should be refridgerated, in case of handling unit `container` |\n| good_customs_information | GROUP | Customs details related to this handling unit |\n\n#### Request Response: Good customs information\n\nCustoms details per good item. This category is a child of a handling unit within category `Good items`.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| value | INTEGER | Value of the contents of the handling unit |\n| currency_code | STRING | Currency of the value of the handling unit |\n| Description | STRING | Description of the contents of the handling unit |\n| hs_code | STRING | Harmonised Systems code for this handling unit, as provided by the shipper |\n\n#### Request Response: Special requirements\n\nSpecific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| air_truck_required | BOOLEAN | To indicate if shipment will require this feature |\n| air_truck_additional_information | STRING | Additional information in case this feature is requested |\n| shock_tilt_required | BOOLEAN | To indicate if shipment will require this feature |\n| shock_tilt_additional_information | STRING | Additional information in case this feature is requested |\n| unique_handling_required | BOOLEAN | To indicate if shipment will require this feature |\n| unique_handling_additional_information | STRING | Additional information in case this feature is requested |\n| chemical_magnetic_concerns | BOOLEAN | To indicate if shipment will require this feature |\n| chemical_magnetic_additional_information | STRING | Additional information in case this feature is requested |\n| unique_warehousing_required | BOOLEAN | To indicate if shipment will require this feature |\n| unique_warehousing_additional_information | STRING | Additional information in case this feature is requested |\n| special_transport_required | BOOLEAN | To indicate if shipment will require this feature |\n| special_transport_additional_information | STRING | Additional information in case this feature is requested |\n| special_provider_requirements | BOOLEAN | To indicate if shipment will require this feature |\n| special_provider_additional_information | STRING | Additional information in case this feature is requested |\n| special_lift_fixtures_required | BOOLEAN | To indicate if shipment will require this feature |\n| special_lift_fixtures_additional_information | STRING | Additional information in case this feature is requested |\n\n#### Request Response: Quotes\n\n** Only visible for Shippers** - Details regarding the quotes that have been received. \nIn case, 1 or multiple quotes has been submitted for this request details will be included in the 'quotes' object, with each quote as an individual object in an array. \nEach quote contains 4 categories of information.\n\n| Key | Description |\n| --- | --- |\n| basic_information | Information like, provider name, quote reference and total quoted amount |\n| schedule | Information related to transit times. |\n| cost_details | Individual charge codes and the total quoted amount |\n| additional_details | Instructions or additional comments, can also include *vessel_information* |\n\n#### Vessel information\n\n***Please Note, vessel_information is part of Quotes in Requests, after booking the vessel_information object is part of the Schedule object in the Shipment details API *** \nVessel information is ocean freight specific, and can contain details provided by the provider about vessel departure, arrival and the vessel number (IMO). \nThese details are only present in case they are populated. These details will not be sent as null if missing.\n\nIn similar fashion to other quotes details, the content of `vessel_information` is an array of key value pairs. \nThe potential pairs are:\n\n* Vessel departure : a date in YYYY-MM-DD\n* Arrival in port : a date in YYYY-MM-DD\n* Vessel / IMO : A string containing the IMO number\n \n\n#### Request Response: Available teams\n\n** Only visible for Providers** \nAn object with 1 or multiple available teams that the request can be assigned to - Visible for Providers only. \nAvailable teams also includes a key to indicate if a team is already assigned - `assigned_team` \nOnly 1 provider team can be assigned, assignment can only be undone via the webplatform. \nDetails on how to assign a team are described in the Assign team end-point.\n\nEach available team is listed as an object in the available_teams section. \nThe name of each object is the *provider_reference* needed to assign the team, for instance 'PT12345678' \nEach object contains the following details:\n\n| Key | Value | Description |\n| --- | --- | --- |\n| team_name | STRING | Name of the provider team, assigned by Cargobase |\n| supported_freight_modes | ARRAY | Requested freight modes, supported by this team |\n| rate_card_available | BOOLEAN | Indicator if a rate-on-file is available to automatically add a quote to the request |", "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "shipment_reference", "in": "path", "schema": { "type": "string", "pattern": "^S[-\\d]+$" }, "required": true, "description": "Replace S12345678 with the relevant Shipment ID", "example": "S12345678" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Request Detail" } }, "/api/1/requests/{shipment_reference}/assign/": { "put": { "tags": [ "Quote Requests" ], "summary": "Assign team", "description": "## Purpose\nA simple end-point to assign a provider team. This is needed before submitting a quote, or in case a rate-card is available but multiple teams could apply for the same request.\n\n## Access\nA provider can only assign teams associated with their account. PUT actions for other shipments or teams are rejected.\n\nAn access token is required to POST to this end-point. \nContact [support@cargobase.com](mailto:support@cargobase.com?subject=Token) to obtain your token. \n\n## Request URI\n```\nPUT https://pluto.cargobase.com/api/1/requests/S12345678/assign/\nContent-Type: application/json\nAuthorization: Token 'your_token_here'\n```\n\n## Message body definition\n|\tPUT parameter\t|\tValue\t|\tRequired\t|\n| \t-----------------\t| -------------\t| -------------\t|\n|\tprovider_reference\t\t|\tSTRING - The provider team team reference number as mentioned in the request\t|\tYes\t|\n\n## Event types\nEvent types are used to categorise your updates. You do not need to send an event-type, however if you do it has to be one of the following categories.\n\n\n## Message body sample\n### Regular update\n```\n{\n \"primary_tracking_number\": \"PT1234678\"\n}\n```\n\n## Status codes\n|\tStatus\t|\tDescription\t|\tResolution\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\t200\t|\tTeam is assigned\t|\t--\t|\n|\t400\t|\tBad Request\t| Most often this means that a team is already assigned\t| \n|\t403\t|\tForbidden \t|\tCheck Authentication credentials\t|\n|\t404\t|\tNot Found \t|\tCheck the shipment ID in the URL\t|\n|\t415\t|\tUnsupported media type\t|\tAdd Content-Type: application/json\t|\n\n### Status code 200\nStatus code 201 signifies that the message is well received, and a confirmation number is provided in the response\n\n```\n{\n \"message\": \"Team is assigned\"\n}\n```", "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "examples": { "assignTeam": { "summary": "Assign provider team", "value": { "provider_reference": "PT12345678" } } } } } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'Your_token' with your own token.", "example": "Token your_token_here" }, { "name": "shipment_reference", "in": "path", "schema": { "type": "string", "pattern": "^S[-\\d]+$" }, "required": true, "description": "Replace with the Shipment ID of the request.", "example": "S12345678" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Assign team" } }, "/api/1/quotes/{quotation_reference}/": { "put": { "tags": [ "Quote Requests" ], "summary": "Update Quote", "description": "The Update Quote end-point can be used to update existing Quotes submitted by you. This end-point is only available to providers. \nNot all details can be updated - in some cases you should cancel the existing quote and submit an alternative. \nYou can use this end-point to submit a cancelation.\n\n**Note** This end-point only applies to Providers\n\n## Request URI\n\n```\nPUT https://pluto.cargobase.com/api/1/quotes/{quote_reference}\nContent-Type: application/json\nAuthorization: Token your_token_here\n\n```\n\n{quote_reference} = The 9 character quote reference, starting with a 'Q'\n\n## Known issues\n\n* None, at the moment. If you find anything; please reach out to [support@cargobase.com](mailto:support@cargobase.com)\n \n\n## Body message\n\nContents of the body message can be dependant on the freight mode that you are quoting on. \nAt this moment, only OBC, Regular Air Freight and Next Flight Out quotes are supported.\n\nThe body message of the update is very similar to the original quote submitted by you. \nHowever, certain fields cannot be updated and others are mandatory. \nAdditional cost details can only be replaced in full. \nThe description below compares the body message of the Update to the original Quote message.\n\n### Main object categories\n\n| Category parameter | Purpose | Requirement |\n| --- | --- | --- |\n| organization | Shipment references, such as Shipment ID and provider team | Contains mandatory elements |\n| service | Details such as freight mode, quote title and other service characteristics | Fully optional, can be omitted from update |\n| financial | Generic financial details | Fully optional, can be omitted from update |\n| cost_items | Specific mandatory cost items | ully optional, can be omitted from update |\n| additional_cost_data | Additional individual cost items | should be omitted, or replaced in full! |\n| schedule | Details such as expected pickup and delivery and quote validity | Fully optional, can be omitted from update |\n\n#### organization values\n\n| Key | Value | Purpose | Instruction |\n| --- | --- | --- | --- |\n| shipment_id | STRING | The shipment ID (S12345678) | Should not be sent - cannot be updated |\n| *request_status* | *STRING* | (Open, Canceled, Confirmed) | Mandatory |\n| provider_team | STRING | Should not be sent - cannot be updated | Should not be sent - cannot be updated |\n| quoted_by | STRING | E-mail address of the quotee - this has to be an activa Cargobase account | Optional, can be updated |\n\n#### service values\n\n| Key | Value | Purpose | Instruction |\n| --- | --- | --- | --- |\n| freight_mode | STRING | Should not be sent - cannot be updated | Should not be sent - cannot be updated |\n| max_weight | FLOAT | The maximum weight the Courier can travel with | Optional, can be updated - OBC Only |\n| max_weight_UOM | BOOLEAN | KG or LBS for the max_weight value | Optional, can be updated - OBC Only |\n| chargeable_weight | FLOAT | Chargeable weight for shipment | Optional, can be updated - Air freight / NFO Only |\n| weight_UOM | FLOAT | KG or LBS for the chargeable_weight value | Optional, can be updated - Air freight / NFO Only |\n| quote_title | BOOLEAN | Title of your quote, to distinguish in case of multiple quotes | Optional, can be updated |\n| primary_tracking_number | BOOLEAN | Your internal reference, or future tracking number | Optional, can be updated |\n\n#### financial values\n\n| Key | Value | Purpose | Instruction |\n| --- | --- | --- | --- |\n| quote_currency | ISO 4217:2015 STRING | Currency of all cost items in your quote | Optional, can be updated |\n| not_included | STRING | Description of quote scope boundaries | Optional, can be updated |\n| cost_details | OBJECT | Specific mandatory cost items | Optional, can be updated |\n\n##### cost_details values\n\n| Key | Value | Purpose | Instruction |\n| --- | --- | --- | --- |\n| quoted_amount | DECIMAL | OBC base fee | Optional, can be updated - OBC Only |\n| total_excess_cost | DECIMAL | Optional excess cost | Optional, can be updated - OBC Only |\n| air_freight_charges | DECIMAL | Air freight / NFO base fee | Optional, can be updated - Regular air freight / NFO Only |\n| additional_cost_data | OBJECT | Optional additional cost items | Optional - can only be updated in full! |\n\n###### additional_cost_data values\n\n**Note** Additional cost items can only be updated in full. You cannot update a single cost item - all items should be sent in again.\n\n| Key | Value | Purpose | Instruction |\n| --- | --- | --- | --- |\n| additional_cost_description | STRING | Description of additional cost item | Conditional |\n| additional_cost_item_amount | DECIMAL | Amount of the additional cost item | Conditional |\n\n**Note** Multiple additional cost items can be added - as dictionary objects within `additional_cost_data`\n\n#### schedule values\n\n| Key | Value | Purpose | Instruction |\n| --- | --- | --- | --- |\n| expected_pickup_date | TIMESTAMP | Expected pickup date, format `YYYY-MM-DD` | Optional, can be updated |\n| expected_pickup_time | TIMESTAMP | Expected pickup time, format `HH:MM` | Optional, can be updated |\n| expected_stop1_date | TIMESTAMP | Expected delivery date, format `YYYY-MM-DD` | Optional, can be updated |\n| expected_stop1_time | TIMESTAMP | Expected delivery time, format `HH:MM` | Optional, can be updated |\n| quote_validity_date | STRING | Quote validity date, format `YYYY-MM-DD` | Optional, can be updated |\n| quote_validity_time | STRING | Quote validity time, format `HH:MM`
Please note, time is in line with personal preferences - contact Support to request changes | Optional, can be updated |\n\n## Error Messages\n\n| Description | Resolution |\n| --- | --- |\n| Status is missing | Please ensure your update includes the right status |\n| Shipment is no longer available | Shipment is no longer available for quotations |\n| An issue occurs with total quoted value, or underlying cost items | An issue exists with the total quoted amount or underlying cost items |", "requestBody": { "required": true, "description": "Updating a quote and canceling one use the same call. request_status is Open, Canceled, or Confirmed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "updateAir": { "summary": "Update air or NFO charges", "description": "request_status stays Open. Do not send shipment_id, provider_team, or freight_mode.", "value": { "organization": { "request_status": "Open", "quoted_by": "quotes@example.com" }, "service": { "chargeable_weight": 575, "weight_UOM": "kg", "quote_title": "Air quote updated", "primary_tracking_number": "17612345678" }, "financial": { "quote_currency": "EUR", "not_included": "Wait time is charged separately.", "cost_details": { "air_freight_charges": 2, "additional_cost_data": [ { "additional_cost_description": "Pickup charge", "additional_cost_item_amount": 172 } ] } } } }, "updateObc": { "summary": "Update OBC", "value": { "organization": { "request_status": "Open", "quoted_by": "quotes@example.com" }, "service": { "max_weight": 12, "max_weight_UOM": "kg", "quote_title": "OBC quote updated" }, "financial": { "quote_currency": "EUR", "not_included": "Excess weight above 12 kg is excluded.", "cost_details": { "quoted_amount": 900, "total_excess_cost": 50 } } } }, "cancel": { "summary": "Cancel quote", "description": "request_status Canceled. Service and financial blocks can be omitted.", "value": { "organization": { "request_status": "Canceled", "quoted_by": "quotes@example.com" } } } } } } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" }, { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "quotation_reference", "in": "path", "schema": { "type": "string", "pattern": "^Q[-\\d]+$" }, "required": true, "description": "Quotation reference number (e.g. `Q12345678`).", "example": "Q12345678" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Update Quote" } }, "/api/1/shipments/{shipment_reference}/": { "get": { "tags": [ "Shipments" ], "summary": "Shipment Detail", "description": "The Shipment Detail end-point can be used to retrieve all specifics of a Shipment. \nHowever, please be aware; if a Shipment has not been awarded, you will need the Request Detail end-point to view the specifics.\n\n## Request URI\n\n```\nGET https://pluto.cargobase.com/api/1/shipments/`SHIPMENT_ID`\nAuthorization: Token your_token_here\n\n```\n\n## Status codes\n\n| Status | Description | Resolution |\n| --- | --- | --- |\n| 200 | OK | \\-- |\n| 403 | Forbidden | check Authentication token, or status of the request |\n| 404 | Not Found | Check the shipment ID |\n\n## Request Response\n\n### Shipment Response categories\n\nThe response is divided into 6 possible categories for shippers and 6 for providers, these are:\n\n| Category | Definition |\n| --- | --- |\n| organization | Details related to the organization, such as WBS Codes or Cost Centers |\n| service | Details related to the service, such as freight mode, incoterms or clearance instructions |\n| schedule | Details related to pickup & delivery timing and locations |\n| good_items | Details related to the packing list |\n| good_customs_information | Customs details per good item |\n| special_requirements | Specific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most. |\n\n#### Shipment Response: Organization\n\nDetails related to the organization, such as WBS Codes or Cost Centers.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| shipment_id | STRING | The request ID |\n| requestor | STRUBG | The name of the person that created this request |\n| shipment_status | STRING | Current status of the shipment, see list for potential status below |\n| shipment_book_datetime | TIMESTAMP | Format **YYYY-MM-DD HH:MM:SS** |\n| shipment_approved_by | STRING | Name of person that performed final booking |\n| shipment_booked_by | STRING | Name of person that initiated booking |\n| title | STRING | Title of the Request, as provided by the Shipper |\n| location | STRING | Name of payment location for this shipment |\n| cost_center | STRING | Value entered in the cost_center field, the shipper might use a custom label for this field and therefore not recognise the term `cost_center` |\n| custom_field1 | STRING | Value entered in the custom_field1 field, the shipper might use a custom label for this field and therefore not recognise the term `custom_field` |\n| reason_code | STRING | Value entered in the reason_code field, the shipper might use a custom label for this field and therefore not recognise the term `reason_code` |\n| goods_confirmation_type | STRING | Details related to the status of the packing list, only available to some. Status can be `Estimated` or `Finalised` |\n| good_items | GROUP | Packing list with details |\n| special_requirements | GROUP | Specific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most. |\n\n#### Shipment status options\n\n| Status | Definition |\n| --- | --- |\n| Booked | An awarded shipment with a pickup time in the future |\n| In Transit | An active shipment expected to be in transit |\n| Delayed | An active shipment where the ETA has passed |\n| Delivered | A shipment that has a POD |\n| Canceled | A shipment that was canceled after being awarded |\n\n#### Shipment Response: Service\n\nDetails related to the service, such as requested freight mode, incoterms or clearance instructions.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| incoterm | STRING | The requested incoterm |\n| delivery_service_level | INTEGER | Number of days associated with Service level, not available for most |\n| export_clearance | STRING | Indicator if Export clearance is expected, and what kind |\n| export_clearance_instructions | STRING | Instructions related to Export clearance |\n| transit_clearance | STRING | Indicator if Transit clearance is expected, and what kind |\n| transit_clearance_instructions | STRING | Instructions related to Transit clearance |\n| import_clearance | STRING | Indicator if Import clearance is expected, and what kind |\n| import_clearance_instructions | STRING | Instructions related to Import clearance |\n| insurance | BOOLEAN | Indicator to see if the provider is expected to arrange shipment insurance |\n| insurance_instructions | STRING | Instructions related to a positive insurance request |\n| service_requirement | STRING | Related to Door-to-Door, Door-to-Port, Port-to-Door or Port-to-Port but abbreviated in a TLA |\n| freight_mode | STRING | The freight mode of the shipment - see freight mode options below |\n| road_freight_type | STRING | Description of road freight type, in case of road freight |\n| provider | STRING | Name of the awarded party |\n| quote_id | STRING | Reference number of the selected quote |\n| airline | STRING | IATA Airline code, if available |\n| flight_number | STRING | Flight number, if available |\n| primary_tracking_number | STRING | Main tracking number, used for automated tracking events |\n| mawb | STRING | Master Airway Bill number, for air cargo tracking |\n| other_tracking_number | STRING | Any additional tracking reference |\n\n##### Freight mode values\n\n* Air charter\n* Next flight out (NFO)\n* Ocean freight\n* Rail freight\n* Regular air freight\n* Road freight\n* Parcel\n* On board courier (OBC)\n \n\n#### Shipment Response: Schedule\n\nDetails related to pickup & delivery timing and locations.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| pickup_airport_code | STRING | IATA Airport code, if identified otherwise `null` |\n| pickup_airport | STRING | Airport Name, if identified otherwise `null` |\n| pickup_seaport_code | STRING | Seaport code, if identified otherwise `null` |\n| pickup_seaport | TYPE | Seaport name, if identified otherwise `null` |\n| pickup_street | STRING | Pickup street address |\n| pickup_address_name | STRING | Pickup company name |\n| pickup_state | STRING | The pickup State in case of US or Mexico |\n| pickup_zipcode | STRING | The pickup postal code |\n| pickup_city | STRING | The pickup city |\n| pickup_country | STRING | The pickup country |\n| quoted_pickup_date | TIMESTAMP | Quoted pickup date, format `YYYY-MM-DD` |\n| quoted_pickup_time | TIMESTAMP | Quoted pickup time, format `HH:MM` |\n| actual_pickup_date | TIMESTAMP | Quoted or Updated Pickup date. |\n| actual_pickup_time | TIMESTAMP | Quoted or Updated Pickup time. |\n| pickup_timezone | STRING | Timezone name |\n| pickup_notes | STRING | Additional pickup notes |\n| pickup_contact_name | STRING | Name of contact person at pickup location |\n| pickup_contact_phone | STRING | Phone number of contact person at pickup location |\n| pickup_contact_email | STRING | Email of contact person at pickup location |\n| pickup_address_type | STRING | Can be `Address`, `Seaport` or `Airport` |\n| stop1_airport | STRING | Airport Name, if identified otherwise `null` |\n| stop1_seaport_code | STRING | Seaport code, if identified otherwise `null` |\n| stop1_seaport | TYPE | Seaport name, if identified otherwise `null` |\n| stop1_street | STRING | Delivery street address |\n| stop1_address_name | STRING | Delivery company name |\n| stop1_state | STRING | The delivery State in case of US or Mexico |\n| stop1_zipcode | STRING | The delivery postal code |\n| stop1_city | STRING | The delivery city |\n| stop1_country | STRING | The delivery country |\n| stop1_quoted_delivery_date | TIMESTAMP | Quoted delivery date, format `YYYY-MM-DD` |\n| stop1_quoted_delivery_time | TIMESTAMP | Quoted deliverytime, format `HH:MM` |\n| stop1_actual_delivery_date | TIMESTAMP | Quoted or Updated delivery date. |\n| stop1_actual_delivery_time | TIMESTAMP | Quoted or Updated delivery time. |\n| stop1_notes | STRING | Additional delivery notes |\n| stop1_contact_name | STRING | Name of contact person at delivery location |\n| stop1_contact_phone | STRING | Phone number of contact person at delivery location |\n| stop1_contact_email | STRING | Email of contact person at delivery location |\n| stop1_address_type | STRING | Can be `Address`, `Seaport` or `Airport` |\n| vessel_information | OBJECT | **For Ocean Freight Only** Details with regards to vessel departure, delivery and IMO |\n\n#### Vessel information\n\n***Please Note, vessel_information is part of Schedule for Shipments, but part of Quotes in Requests***\n\nVessel information is ocean freight specific, and can contain details provided by the provider about vessel departure, arrival and the vessel number (IMO). \nThese details are only present in case they are populated. These details will not be sent as null if missing.\n\nIn similar fashion to other quotes details, the content of `vessel_information` is an array of key value pairs. \nThe potential pairs are:\n\n* Vessel departure : a date in YYYY-MM-DD\n* Arrival in port : a date in YYYY-MM-DD\n* Vessel / IMO : A string containing the IMO number\n \n\n#### Shipment Response: Good items\n\nDetails related to the packing list. This category is a child of `Organization`. \nThese values are grouped per handling unit, each shipment can have multiple handling units. \nEach shipment can also have multiple handling units of the same type, but differences in dimensions, notes or classifications.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| units | INTEGER | Number of this type of handling unit |\n| handling_unit | STRING | Handling unit type |\n| length | DOUBLE | Length value |\n| height | DOUBLE | Height value |\n| width | DOUBLE | Width value |\n| m_unit | STRING | LxWxH unit of measurement, can be `cm` or `inch` |\n| weight | INTEGER | Weight of individual handling unit piece, should be multiple by number of units for total Weight |\n| w_unit | STRING | Weight unit of measurement, can be `kg` or `lbs` |\n| stackable | BOOLEAN | Indicator if individual piece can be stacked |\n| hazardous | BOOLEAN | Indicator if goods are considered hazardous |\n| crating_required | BOOLEAN | Indicator if the provider is requested to provide crating, will be `null` for most |\n| crating_required_by_date | TIMESTAMP | Date & Time of final possibility to provide crating services, will be `null` for most |\n| is_dangerous_good | BOOLEAN | Indicator if contents are classified as a Dangerous good |\n| dangerous_good_value | INTEGER | Indicator of DG Category |\n| other_instructions | STRING | Description in case of handling unit `other` |\n| additional_information | STRING | Additional instructions related to these goods |\n| container_type | STRING | Description of container type, in case of handling unit `container` (e.g. 20Ft standard) |\n| refrigerated_container | BOOLEAN | Indicator if container should be refridgerated, in case of handling unit `container` |\n| good_customs_information | GROUP | Customs details related to this handling unit |\n\n#### Shipment Response: Good customs information\n\nCustoms details per good item. This category is a child of a handling unit within category `Good items`.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| value | INTEGER | Value of the contents of the handling unit |\n| currency_code | STRING | Currency of the value of the handling unit |\n| Description | STRING | Description of the contents of the handling unit |\n| hs_code | STRING | Harmonised Systems code for this handling unit, as provided by the shipper |\n\n#### Shipment Response: Special requirements\n\nSpecific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most.\n\n| Key | Value | Description |\n| --- | --- | --- |\n| air_truck_required | BOOLEAN | To indicate if shipment will require this feature |\n| air_truck_additional_information | STRING | Additional information in case this feature is requested |\n| shock_tilt_required | BOOLEAN | To indicate if shipment will require this feature |\n| shock_tilt_additional_information | STRING | Additional information in case this feature is requested |\n| unique_handling_required | BOOLEAN | To indicate if shipment will require this feature |\n| unique_handling_additional_information | STRING | Additional information in case this feature is requested |\n| chemical_magnetic_concerns | BOOLEAN | To indicate if shipment will require this feature |\n| chemical_magnetic_additional_information | STRING | Additional information in case this feature is requested |\n| unique_warehousing_required | BOOLEAN | To indicate if shipment will require this feature |\n| unique_warehousing_additional_information | STRING | Additional information in case this feature is requested |\n| special_transport_required | BOOLEAN | To indicate if shipment will require this feature |\n| special_transport_additional_information | STRING | Additional information in case this feature is requested |\n| special_provider_requirements | BOOLEAN | To indicate if shipment will require this feature |\n| special_provider_additional_information | STRING | Additional information in case this feature is requested |\n| special_lift_fixtures_required | BOOLEAN | To indicate if shipment will require this feature |\n| special_lift_fixtures_additional_information | STRING | Additional information in case this feature is requested |\n\n## Known issues\n\n* None at the moment", "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "shipment_reference", "in": "path", "schema": { "type": "string", "pattern": "^S[-\\d]+$" }, "required": true, "description": "Replace S12345678 with the corresponding Shipment ID", "example": "S12345678" } ], "responses": { "200": { "description": "OK", "headers": { "Date": { "schema": { "type": "string", "example": "Thu, 25 Apr 2019 02:02:27 GMT" } }, "Content-Type": { "schema": { "type": "string", "example": "application/json" } }, "Content-Length": { "schema": { "type": "integer", "example": "3414" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "x-amzn-RequestId": { "schema": { "type": "string", "example": "2cabbf2e-66fe-11e9-a019-d1d941e40007" } }, "Strict-Transport-Security": { "schema": { "type": "string", "example": "max-age=63072000; includeSubdomains;" } }, "Allow": { "schema": { "type": "string", "example": "GET, HEAD, OPTIONS" } }, "x-amzn-Remapped-Content-Length": { "schema": { "type": "integer", "example": "3414" } }, "X-Frame-Options": { "schema": { "type": "string", "example": "SAMEORIGIN" } }, "Content-Language": { "schema": { "type": "string", "example": "courier-network-inc" } }, "x-amzn-Remapped-Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Set-Cookie": { "schema": { "type": "string", "example": "django_language=en; Path=/" } }, "x-amz-apigw-id": { "schema": { "type": "string", "example": "YrA_8FASvHcFf4A=" } }, "Vary": { "schema": { "type": "string", "example": "Accept, Accept-Language, Origin, Cookie" } }, "x-amzn-Remapped-Server": { "schema": { "type": "string", "example": "nginx/1.10.3 (Ubuntu)" } }, "x-amzn-Remapped-Date": { "schema": { "type": "string", "example": "Thu, 25 Apr 2019 02:02:27 GMT" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "organization": { "shipment_id": "S12345678", "requestor": "Alex van Kampen", "shipment_status": "In transit", "shipment_book_datetime": "2019-04-25 00:09:23", "shipment_approved_by": "Alex van Kampen", "shipment_booked_by": "Pavel Makarevich", "title": "Title of the Shipment", "location": "Singapore", "cost_center": "123.AB.44", "custom_field1": "", "reason_code": "AT - API Tutorial", "good_items": [ { "units": 35, "handling_unit": "carton", "length": 23, "height": 13, "width": 17, "m_unit": "inch", "weight": 17, "w_unit": "lbs", "stackable": false, "hazardous": false, "crating_required": null, "is_dangerous_good": null, "crating_required_by_date": null, "other_instructions": "", "additional_information": "", "container_type": null, "refrigerated_container": null, "custom_size": "", "custom_size_dimension_unit": "meter", "dangerous_good_value": "", "good_customs_information": [ { "value": 1, "currency_code": "USD", "description": "Blinker fluid", "hs_code": "", "good_customs_information_attachments": [] } ] } ], "special_requirements": { "air_truck_required": null, "air_truck_additional_information": "", "shock_tilt_required": null, "shock_tilt_additional_information": "", "unique_handling_required": null, "unique_handling_additional_information": "", "chemical_magnetic_concerns": null, "chemical_magnetic_additional_information": "", "unique_warehousing_required": null, "unique_warehousing_additional_information": "", "special_transport_required": null, "special_transport_additional_information": "", "special_provider_requirements": null, "special_provider_additional_information": "", "special_lift_fixtures_required": null, "special_lift_fixtures_additional_information": "" } }, "service": { "incoterm": "EXW", "delivery_service_level": null, "export_clearance": null, "export_clearance_instruction": null, "transit_clearance": null, "transit_clearance_instruction": null, "import_clearance": true, "import_clearance_instruction": "Provider should prepare proper import documentation", "insurance": false, "insurance_instructions": "", "service_requirement": "", "freight_mode": "Next flight out (NFO)", "provider": "Movers & Shakers", "quote_id": "Q44112234", "airline": "KLM", "flight_number": "836", "primary_tracking_number": "29471924719285", "mawb": "", "other_tracking_number": "", "road_freight_type": "" }, "schedule": { "pickup_airport_code": null, "pickup_airport": null, "pickup_seaport_code": null, "pickup_seaport": null, "pickup_country": "Singapore", "pickup_postal_code": "429106", "pickup_state": null, "pickup_city": "Singapore", "pickup_addressline1": "6 Ean Kiam Place", "pickup_addressline2": "", "quoted_pickup_date": "2019-04-24", "quoted_pickup_time": "11:00:00", "actual_pickup_date": "2019-04-24", "actual_pickup_time": "18:00:00", "pickup_timezone": "GMT+8", "pickup_notes": "", "pickup_contact_name": "Alex van Kampen", "pickup_contact_phone": "+65 1234 5678", "pickup_contact_email": "hello@cargobase.com", "pickup_address_type": "Address", "stop1_airport_code": null, "stop1_airport": null, "stop1_seaport_code": null, "stop1_seaport": null, "stop1_country": "Netherlands", "stop1_postal_code": "1051ML", "stop1_state": null, "stop1_city": "Amsterdam", "stop1_addressline1": "Wichersstraat 48", "stop1_addressline2": "", "stop1_quoted_delivery_date": "2019-04-25", "stop1_quoted_delivery_time": "13:00:00", "stop1_actual_delivery_date": "2019-04-25", "stop1_actual_delivery_time": "17:56:00", "stop1_timezone": "GMT+1", "stop1_notes": "", "stop1_contact_name": "Max van Pankele", "stop1_contact_phone": "+31 6 30645942", "stop1_contact_email": "max@acmeinc.com", "stop1_address_type": "Address" } } } } } }, "x-displayName": "Shipment Detail" }, "put": { "tags": [ "Shipments" ], "summary": "Cancel shipment", "description": "The Shipment detail end-point can be used to cancel any booked shipment. A cancelation should only be done if pickup has not truly occurred. Also, an LSP might charge a cancelation fee or still invoice the full quoted value of the shipment. The options of this end-point are intentionally limited.\n\n**Note** This end-point only applies to Shippers\n\n## Request URI\n```\nPUT https://pluto.cargobase.com/api/1/shipments/S12345678\nContent-Type: application/json\nAuthentication: Token 'your_token_here'\n```\n\n## Body message\nFor reasons of consistency, the body message contains the organization object. Other familiar object categories cannot be updated and are not part of this PUT request.\n\n### Main object categories\n|\tCategory parameter\t|\tPurpose\t|\n| \t-----------------\t| -------------\t|\n|\torganization\t|\tTo cancel the request\t|\n\n#### organization values \n|\tKey\t|\tValue\t|\tMandatory\t|\tPurpose\t|\tParent object\t|\n| \t-----------------\t|\t-------------\t|\t-------------\t|\t-------------\t|\t-------------\t|\n|\tchanged_by \t| STRING\t| OPTIONAL\t|\tThis can be the email id of another Cargobase account id\t|\torganization \t|\n|\tshipment_status \t|\tSTRING\t| OPTIONAL\t|\tCan only be used to cancel a shipment, expecte value: 'canceled'\t|\torganization \t|\n|\tcancel_comment \t|\tSTRING\t| OPTIONAL\t|\tCan be used to share additional feedback to the provider, use only in combination with request_status\t|\torganization \t|\n\n## Status codes\n|\tStatus\t|\tDescription\t|\tResolution\t|\n| \t---------\t| ----------------\t| ----------------\t|\n|\t201\t|\tCreated\t|\t\"Success : true\"\t|\n|\t403\t|\tForbidden \t|\tcheck Authentication token\t|", "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "examples": { "cancel": { "summary": "Cancel shipment", "value": { "organization": { "changed_by": "username@company.com", "shipment_status": "canceled", "cancel_comment": "This shipment will be canceled, we understand the LSP might charge a cancelation fee." } } } } } } }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "header", "schema": { "type": "string" }, "description": "Replace 'your_token_here' with your token.", "example": "Token your_token_here" }, { "name": "shipment_reference", "in": "path", "schema": { "type": "string", "pattern": "^S[-\\d]+$" }, "required": true, "example": "S12345678", "description": "Shipment reference number (e.g. `S12345678`)." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } } }, "x-displayName": "Cancel shipment" } }, "/api/1/order/create/": { "post": { "summary": "Create Order", "description": "Creates a new shipping order with scheduling, organizational info, and packing list.", "operationId": "createOrder", "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }, "examples": { "quickRequest": { "summary": "Create a quick request order", "value": { "quick_request": { "title": "Sample Quick Request Title", "comments": "Sample Test comments." }, "organizational": { "location_ref": "L1234567", "cost_center": "CC12345", "reason_code": "RC67890", "reason_code_group": "RCG112233", "custom_field_01": "Custom Value 01", "custom_field_02": "Custom Value 02", "custom_field_03": "Custom Value 03", "custom_long_field_01": "Custom Long Field 01", "goods_confirmation_type": "Estimated" }, "schedule": { "pickup_address_type": "Commercial", "pickup_address_name": "Main Warehouse", "pickup_company_name": "Logistics Co.", "pickup_city": "New York", "pickup_state": "NY", "pickup_country": "USA", "pickup_airport_code": "JFK", "pickup_airport": "John F. Kennedy International Airport", "pickup_seaport": "Port of New York", "pickup_seaport_code": "NYK", "pickup_country_code": "US", "pickup_before_date": "2024-07-20", "pickup_before_time": "16:00:00", "pickup_ready_date": "2024-07-15", "pickup_ready_time": "08:00:00", "pickup_hours_from": "08:00:00", "pickup_hours_to": "17:00:00", "pickup_timezone": "EST", "pickup_cargo_ready": "After", "pickup_notes": "Handle with care", "pickup_street_line2": "Building B", "delivery_hours_from": "09:00:00", "delivery_hours_to": "18:00:00", "stop1_address_type": "Residential", "stop1_company_name": "Recipient Corp.", "stop1_notes": "Leave at front door", "stop1_street_line2": "Apt 5B", "stop1_street": "1234 Elm St", "pickup_street": "5678 Oak St", "stop1_country": "USA", "stop1_state": "CA", "stop1_country_code": "US", "stop1_zipcode": "90001", "stop1_city": "Los Angeles", "stop1_address_name": "Recipient Home", "stop1_contact_name": "Jane Doe", "stop1_contact_phone": "555-1234", "stop1_contact_email": "jane.doe@example.com", "stop1_after_date": "2024-07-22", "stop1_after_time": "10:00:00", "stop1_before_date": "2024-07-23", "stop1_before_time": "16:00:00", "stop1_timezone": "PST", "delivery_cargo_ready": "Before", "stop1_airport_code": "LAX", "stop1_airport": "Los Angeles International Airport", "stop1_seaport_code": "LAX", "stop1_seaport": "Port of Los Angeles" }, "packing_list": [ { "handling_unit": "Pallet", "handling_unit_value": "1", "units": 10, "length": 1.2, "width": 0.8, "height": 1, "m_unit": "meters", "hazardous": false, "container_type": "Standard", "temperature_control_required": true, "temperature_control_value": "3", "temperature_controlled_custom_value": "Store at 5°C", "cbm_scope": "Full", "l_w_h_cbm_total": 0.96, "l_w_h_cbm_piece": 0.096, "weight_piece": 50, "weight_total": "500.0", "w_unit": "kg", "stackable": true, "is_dangerous_good": false, "dangerous_good_value": "", "additional_information": "Handle with care", "crating_required": true, "crating_required_by": "2024-07-20", "additional_text": "Ensure packaging integrity", "nmfc_class": "Class 70", "good_customs_information": [ { "value": 8000, "currency_code": "USD", "description": "Gear R", "hs_code": "E2" } ], "additional_field": "Extra details" } ], "service": { "incoterms": null, "incoterm_instructions": "", "service_level": "", "service_type": null, "export_clearance": "API_NO_IMPORT_EXPORT_CLEARANCE", "export_clearance_instructions": "", "transit_clearance": "API_NO_IMPORT_EXPORT_CLEARANCE", "transit_clearance_instructions": "", "import_clearance": "API_NO_IMPORT_EXPORT_CLEARANCE", "import_clearance_instructions": "", "insurance": null, "insurance_instructions": "", "special_requirements": {} } } } } } } }, "responses": { "200": { "description": "Order successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the order was created successfully" }, "order_id": { "type": "string", "example": "ORD-123456", "description": "Unique identifier for the created order" } } } } } }, "400": { "description": "Bad Request – Validation errors or missing fields" }, "401": { "description": "Unauthorized – Invalid or missing token" } }, "tags": [ "Quick Requests" ], "x-displayName": "Create Order" } }, "/api/1/carrier-tracking-webhook": { "post": { "tags": [ "Tracking" ], "summary": "Post carrier tracking update", "description": "## Purpose\nMain provider endpoint for posting a single tracking update (milestone) — and optionally documents — onto a Cargobase shipment.\n\n> **Check a payload before you send it:** paste it into the [Payload Doctor](/tools/payload-doctor?endpoint=carrier-tracking-webhook) to see what the API will reject, or to get help with an error response.\n\n## Access\nProviders can only post updates for shipments associated with their account. Posts for other shipments are rejected.\n\n## Content types\nYou can send either:\n\n1. **`application/json`** — tracking payload as the JSON body (no file upload).\n2. **`multipart/form-data`** — required when uploading documents:\n - `data` (text): the tracking payload as a **JSON string** (same fields as the tables below)\n - `documents` (file): the file to attach (repeat the key for multiple files)\n\nSend one update per request. A JSON array of updates is rejected.\n\n## Request URI\n```\nPOST {ENV_DOMAIN}/api/1/carrier-tracking-webhook\nAuthorization: Token your_token_here\n```\n\n## Form-data keys (when uploading files)\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| data | STRING (JSON) | Yes | Tracking payload as a JSON string — same fields as the body tables below |\n| documents | FILE | No | Document file to attach (POD, ARN, HBL, …). Repeat the key for multiple files |\n\n## Body message — root fields\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| tracking_number | STRING | Yes | Carrier / third-party tracking number for this update |\n| tracking_type | STRING | Yes | Free-text source identifier (e.g. primary, or your carrier slug). Not validated |\n| tracking_update_text | STRING | Yes | Event text shown on the timeline. For document uploads, include the document type (POD, ARN, HBL, …) |\n| tracking_status_tag | STRING | Yes | Uppercase, case-sensitive status — see Accepted tracking_status_tag values below |\n| mode_of_transport | STRING | No | air_freight, road_freight, ocean_freight, rail_freight, or parcel_freight. Decides which milestone_details.event_type values are accepted |\n| shipment_id | STRING | No (strongly recommended) | Cargobase shipment reference (e.g. S22316102). Without it the update is not attached to the Cargobase shipment, and its status and timings are not updated |\n| created_time | DATETIME | No (recommended) | When the event was recorded in your system. Used as the event timestamp and for duplicate detection; defaults to the time Cargobase receives the update |\n| event_time | DATETIME | No | When the milestone occurred |\n| event_time_with_timezone | DATETIME | No | Same as event_time with an explicit timezone offset |\n| expected_departure_time | DATETIME | No | Expected departure. Updates the shipment when shipment_id is set |\n| expected_arrival_time | DATETIME | No | Expected arrival / delivery. Updates the shipment when shipment_id is set |\n| actual_departure_time | DATETIME | No | Actual departure. Updates the shipment when shipment_id is set |\n| actual_arrival_time | DATETIME | Conditional | Actual arrival / delivery. Required when tracking_status_tag is DELIVERED. Updates the shipment when shipment_id is set |\n| pod_acceptor | STRING | No | Name of the person who signed for the delivery; recorded with DELIVERED updates |\n| additional_info | OBJECT | No | Free-form carrier-specific key/value object (must be an object, not an array) |\n| bill_of_lading | OBJECT | No | Bill of lading / ocean identifiers — see nested table |\n| flight_information | OBJECT | No | Flight identifiers — see nested table |\n| location | OBJECT | No | Location of this tracking event — see nested table |\n| from | OBJECT | No | Origin / from location (same shape as location) |\n| to | OBJECT | No | Destination / to location (same shape as location) |\n| event_weight | INTEGER | No | Weight associated with this event (whole number) |\n| event_piece | INTEGER | No | Piece count for this event (whole number) |\n| weight | INTEGER | No | Total weight for this tracking number (whole number) |\n| piece | INTEGER | No | Total piece count for this tracking number (whole number) |\n| milestone_details | OBJECT | No | Structured milestone — see nested table |\n| routes | ARRAY | No | Multi-leg route objects — see nested table |\n\nAll DATETIME fields are ISO 8601. Include `Z` or an offset (for example `2026-09-30T08:15:00Z` or `2026-09-30T10:15:00+02:00`); times without one are stored without a timezone.\n\nFields not listed here are ignored.\n\n## Accepted tracking_status_tag values\n\nValues are case-sensitive. `Delivered` or `intransit` is rejected.\n\n| Value | Meaning | Notes |\n| --- | --- | --- |\n| BOOKED | Booking confirmed / shipment booked for transport | Use when the carrier has accepted the booking |\n| INTRANSIT | Shipment is moving / in progress | Default for non-POD document uploads (ARN, HBL, …) and most mid-journey milestones |\n| DELAYED | Shipment is delayed | Include delay context in tracking_update_text when possible |\n| DELIVERED | Shipment delivered | Required: actual_arrival_time. Use for POD document uploads |\n| CANCELLED | Shipment / tracking cancelled | |\n| UNSPECIFIED | Status not mapped to a more specific tag | Prefer a specific tag when you can |\n\n### Document uploads and status\n\n| Document | tracking_status_tag | Also send |\n| --- | --- | --- |\n| Proof of delivery (POD) | DELIVERED | actual_arrival_time; put POD in tracking_update_text |\n| Other documents (ARN, HBL, …) | INTRANSIT (or another non-delivered status) | Document type in tracking_update_text |\n\n## Duplicate updates\n\nAn update is skipped — `200` with `No new updates for Tracking Number …` — when an earlier update for the same tracking number has the same `tracking_update_text`, `location.location_text` and `created_time`. `tracking_status_tag` is not part of this check.\n\nAlways send `created_time`, so a retried request is recognised as the same event. Without it, every retry is stored as a new event.\n\n## Nested object — bill_of_lading\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| bill_of_lading_number | STRING | No | Bill of lading (B/L) number |\n| carrier_no | STRING | No | SCAC code identifying the carrier |\n| container_no | STRING | No | Container number (container shipments only) |\n\n## Nested object — flight_information\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| flight_number | STRING | Yes* | Flight number including the airline code (e.g. MH197) |\n| airline | STRING | No | Airline name |\n\n## Nested object — location (also used by from / to)\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| location_text | STRING | No | Free-text location label, shown on the timeline and used for duplicate detection |\n| name | STRING | No | Location / airport / facility name |\n| country | STRING | No | Country name |\n| country_code | STRING | No | Two-letter ISO 3166-1 country code |\n| state | STRING | No | State / province |\n| unlocode | STRING | No | UN/LOCODE (5 characters) |\n| iata_code | STRING | No | IATA airport code (3 letters) |\n| icao_code | STRING | No | ICAO airport code (4 letters) |\n| coordinates | OBJECT | No | Object with lat and lng numbers — both required* |\n\n## Nested object — milestone_details\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| event_type | STRING | Yes* | Milestone type — see Allowed milestone_details.event_type values below |\n| location_type | STRING | Yes* | place_of_receipt, place_of_loading, place_of_transhipment, place_of_discharge, place_of_delivery, or other |\n| initial_quoted_time | DATETIME | No | Time originally quoted for this milestone |\n| confirmed_time | DATETIME | No | Time confirmed by the carrier |\n| estimated_time | DATETIME | No | Current estimated time |\n| actual_time | DATETIME | No | When the milestone actually happened |\n\n## Nested object — routes[]\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| from | OBJECT or null | Yes* | Start of this leg (same shape as location). The key must be present; send null if unknown |\n| to | OBJECT | No | End of this leg (same shape as location) |\n| sequence_id | STRING | No | Order of this leg in the route |\n| flight_number | STRING | No | Flight number for this leg (air) |\n| transport_type | STRING | No | Transport type for this leg (free text) |\n| status | STRING | No | Status of this leg (free text) |\n| piece | INTEGER | No | Piece count on this leg |\n| weight | INTEGER | No | Weight on this leg |\n| departure_datetime | OBJECT | No | `{ \"actual\": DATETIME, \"estimated\": DATETIME }` |\n| arrival_datetime | OBJECT | No | `{ \"actual\": DATETIME, \"estimated\": DATETIME }` |\n\n\\* Required when the parent object is sent.\n\n## Allowed milestone_details.event_type values\n\nValues are lowercase and must match exactly.\n\n| mode_of_transport | Checked | Values |\n| --- | --- | --- |\n| ocean_freight, rail_freight | Yes | `booked`, `pickup`, `gatein`, `load`, `depart`, `arrive`, `unload`, `gateout`, `deliver`, `return`, `pod_berthing`, `ts_berthing`, `unclassified` |\n| road_freight | Yes | `booked`, `pickup`, `departure`, `pre_customs_clearance`, `customs_check_in`, `customs_clearance`, `arrival`, `unloading`, `delivery` |\n| air_freight | No — any value is accepted; use these | `booked_for_transport`, `consignment_received`, `received_from_shipper`, `manifested_on_flight`, `departed`, `transferred_to_another_airline`, `received_from_another_airline`, `received_from_flight`, `arrived_at_destination`, `consignee_notified_of_arrival`, `documentation_delivered_to_consignee`, `consignment_to_be_transferred`, `consignment_cleared_by_customs`, `delivered_to_consignee`, `discrepancy_details`, `prepared_for_loading_on_flights`, `documentation_received`, `freight_on_hand`, `freight_waybill_process` |\n| parcel_freight, or no mode_of_transport | No | Any value |\n\n## Errors\n\nValidation errors return `400` with a `message` that starts with `Something went wrong during update process. Error:`, followed by the field name and the problem. Nested fields are shown as `parent -> field` (for example `routes -> 0 -> from`).\n\n| Status | Message contains | Cause | Fix |\n| --- | --- | --- | --- |\n| 400 | `Invalid JSON body` | The JSON body is not an object | Send one JSON object per request |\n| 400 | `Invalid JSON in 'data'` | The form-data `data` value is not valid JSON | Send the payload as a JSON string in `data` |\n| 400 | `Missing tracking_number required for file uploads.` | `tracking_number` is missing or empty (any content type) | Send `tracking_number` |\n| 400 | `field required` | A required field is missing (the line above names it) | Add the field. Nested required fields only apply when the parent object is sent |\n| 400 | `none is not an allowed value` | A field was sent as `null` | Send a value, or leave the field out if it is optional |\n| 400 | `value is not a valid enumeration member` | `tracking_status_tag`, `mode_of_transport` or `location_type` is not an allowed value | Use one of the listed values exactly, including case |\n| 400 | `actual_arrival_time must be given if tracking_status_tag is Delivered` | `DELIVERED` sent without `actual_arrival_time` | Add `actual_arrival_time` |\n| 400 | `event_type in milestone_details is not one of the possible event_types for …` | `milestone_details.event_type` is not allowed for this `mode_of_transport` | Use a value from Allowed milestone_details.event_type values |\n| 400 | `invalid datetime format` | A DATETIME field is not ISO 8601 | Send for example `2026-09-30T08:15:00Z` |\n| 400 | `value is not a valid integer` | A weight or piece field is not a whole number | Send a whole number |\n| 400 | `value is not a valid dict` | An object field (e.g. `additional_info`) was sent as another type | Send a JSON object |\n| 400 | `'list' object has no attribute 'get'` | The body is an array of updates | Send one update per request |\n| 403 | `Authentication credentials were not provided.` | The `Authorization` header is missing or invalid | Send `Authorization: Token ` |\n| 403 | `You do not have permission to perform this action.` | The token's user cannot post tracking updates | Contact Cargobase to enable tracking access |\n\n## Sample JSON body (no file)\n```json\n{\n \"tracking_number\": \"OMNI-12345\",\n \"shipment_id\": \"S22316102\",\n \"tracking_type\": \"primary\",\n \"mode_of_transport\": \"air_freight\",\n \"tracking_update_text\": \"Departed origin\",\n \"tracking_status_tag\": \"INTRANSIT\",\n \"created_time\": \"2026-09-30T08:15:00.000Z\",\n \"event_time\": \"2026-09-30T08:15:00.000Z\",\n \"expected_arrival_time\": \"2026-10-02T16:00:00.000Z\"\n}\n```\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CarrierTrackingWebhookMultipart" }, "examples": { "inTransit": { "summary": "In-transit milestone (form-data, no file)", "value": { "data": "{\"tracking_number\":\"OMNI-12345\",\"shipment_id\":\"S22316102\",\"tracking_type\":\"primary\",\"mode_of_transport\":\"air_freight\",\"tracking_update_text\":\"Departed origin\",\"tracking_status_tag\":\"INTRANSIT\",\"event_time\":\"2026-09-30T08:15:00.000Z\",\"expected_arrival_time\":\"2026-10-02T16:00:00.000Z\"}" } }, "podWithFile": { "summary": "Delivered / POD (form-data with file)", "value": { "data": "{\"tracking_number\":\"OMNI-12345\",\"shipment_id\":\"S22316102\",\"tracking_type\":\"primary\",\"mode_of_transport\":\"air_freight\",\"tracking_update_text\":\"POD uploaded\",\"tracking_status_tag\":\"DELIVERED\",\"actual_arrival_time\":\"2026-01-08T07:19:00.000Z\",\"event_time\":\"2026-01-08T07:19:00.000Z\"}", "documents": "pod.pdf" } }, "hblWithFile": { "summary": "In-transit HBL upload (form-data with file)", "value": { "data": "{\"tracking_number\":\"OMNI-12345\",\"shipment_id\":\"S22316102\",\"tracking_type\":\"primary\",\"mode_of_transport\":\"air_freight\",\"tracking_update_text\":\"HBL document uploaded\",\"tracking_status_tag\":\"INTRANSIT\",\"event_time\":\"2026-09-30T08:15:00.000Z\",\"expected_arrival_time\":\"2026-10-02T16:00:00.000Z\"}", "documents": "hbl.pdf" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/CarrierTrackingWebhookPayload" }, "examples": { "inTransit": { "summary": "In-transit milestone", "value": { "tracking_number": "OMNI-12345", "shipment_id": "S22316102", "tracking_type": "primary", "mode_of_transport": "air_freight", "tracking_update_text": "Departed origin", "tracking_status_tag": "INTRANSIT", "event_time": "2026-09-30T08:15:00.000Z", "expected_arrival_time": "2026-10-02T16:00:00.000Z" } }, "delivered": { "summary": "Delivered milestone", "value": { "tracking_number": "OMNI-12345", "shipment_id": "S22316102", "tracking_type": "primary", "mode_of_transport": "air_freight", "tracking_update_text": "Delivered to consignee", "tracking_status_tag": "DELIVERED", "created_time": "2026-01-08T07:19:00.000Z", "actual_arrival_time": "2026-01-08T07:19:00.000Z", "pod_acceptor": "Jane Doe" } } } } } }, "responses": { "200": { "description": "Tracking update processed (or no new updates).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Result message. `No new updates for Tracking Number …` means the update repeated an earlier one and was skipped (see *Duplicate updates*)." } } }, "examples": { "success": { "value": { "message": "Generic Tracking Event for Tracking Number OMNI-12345 has been processed successfully." } }, "noNew": { "value": { "message": "No new updates for Tracking Number OMNI-12345." } } } } } }, "400": { "description": "Bad request. Malformed JSON returns `error`; everything else, including validation errors, returns `message`. See *Errors* in the description for causes and fixes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Set when the JSON body, or the form-data `data` value, cannot be parsed." }, "message": { "type": "string", "description": "Set for validation and processing errors. Validation errors start with `Something went wrong during update process. Error:`." } } }, "examples": { "invalidBody": { "summary": "JSON body is not an object", "value": { "error": "Invalid JSON body" } }, "invalidData": { "summary": "form-data `data` is not valid JSON", "value": { "error": "Invalid JSON in 'data'" } }, "missingTrackingNumber": { "summary": "tracking_number missing", "value": { "message": "Missing tracking_number required for file uploads." } }, "missingRequiredFields": { "summary": "Required fields missing", "value": { "message": "Something went wrong during update process. Error: 3 validation errors for GenericTrackingUpdateSchema\ntracking_type\n field required (type=value_error.missing)\ntracking_update_text\n field required (type=value_error.missing)\ntracking_status_tag\n field required (type=value_error.missing)" } }, "invalidStatusTag": { "summary": "tracking_status_tag in the wrong case", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\ntracking_status_tag\n value is not a valid enumeration member; permitted: 'BOOKED', 'INTRANSIT', 'DELAYED', 'DELIVERED', 'CANCELLED', 'UNSPECIFIED' (type=type_error.enum; enum_values=[, , , , , ])" } }, "deliveredWithoutArrivalTime": { "summary": "DELIVERED without actual_arrival_time", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\n__root__\n actual_arrival_time must be given if tracking_status_tag is Delivered (type=assertion_error)" } }, "invalidModeOfTransport": { "summary": "Unknown mode_of_transport", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\nmode_of_transport\n value is not a valid enumeration member; permitted: 'air_freight', 'road_freight', 'ocean_freight', 'rail_freight', 'parcel_freight' (type=type_error.enum; enum_values=[, , , , ])" } }, "invalidDatetime": { "summary": "Datetime not in ISO 8601", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\nevent_time\n invalid datetime format (type=value_error.datetime)" } }, "invalidEventTypeForRoad": { "summary": "event_type not allowed for road_freight", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\n__root__\n event_type in milestone_details is not one of the possible event_types for road_freight (type=assertion_error)" } }, "missingMilestoneLocationType": { "summary": "milestone_details without location_type", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\nmilestone_details -> location_type\n field required (type=value_error.missing)" } }, "missingFlightNumber": { "summary": "flight_information without flight_number", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\nflight_information -> flight_number\n field required (type=value_error.missing)" } }, "routeMissingFrom": { "summary": "Route without the from key", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\nroutes -> 0 -> from\n field required (type=value_error.missing)" } }, "nonIntegerWeight": { "summary": "Weight is not a whole number", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\nweight\n value is not a valid integer (type=type_error.integer)" } }, "additionalInfoNotObject": { "summary": "additional_info is not an object", "value": { "message": "Something went wrong during update process. Error: 1 validation error for GenericTrackingUpdateSchema\nadditional_info\n value is not a valid dict (type=type_error.dict)" } }, "bodyIsArray": { "summary": "Body is an array of updates", "value": { "message": "Something went wrong during update process. Error: 'list' object has no attribute 'get'" } } } } } }, "401": { "description": "Not returned by this endpoint in practice: a missing or invalid token returns `403`." }, "403": { "description": "Forbidden. The token is missing or invalid, or the token's user does not have permission to post tracking updates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "notAuthenticated": { "summary": "Missing or invalid token", "value": { "detail": "Authentication credentials were not provided." } }, "noPermission": { "summary": "No tracking permission", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "x-displayName": "Post carrier tracking update" } }, "/api/1/shipments/{shipment_reference}/tracking/create/": { "post": { "tags": [ "Shipments" ], "summary": "Add tracking number", "description": "## Purpose\nAdd one or more tracking numbers to an awarded shipment. Use this before (or alongside) posting milestones via `POST /api/1/carrier-tracking-webhook`.\n\nOnly one **primary** tracking number is allowed per shipment. The shipment must be awarded and not archived.\n\n## Request URI\n```\nPOST {ENV_DOMAIN}/api/1/shipments/{shipment_reference}/tracking/create/\nContent-Type: application/json\nAuthorization: Token your_token_here\n```\n\n## Sample request body\n```json\n{\n \"references\": [\n {\n \"tracking_type\": \"primary\",\n \"tracking_number\": \"1Z999AA10123456784\"\n }\n ]\n}\n```\n", "parameters": [ { "name": "shipment_reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cargobase shipment reference (for example `S12345678`).", "example": "S12345678" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentTrackingInput" } } } }, "responses": { "201": { "description": "Tracking number(s) added.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CreateShipmentTrackingInput" }, "msg": { "type": "string", "example": "1Z999AA10123456784 added successfully" } } } } } }, "400": { "description": "Validation error (for example a primary tracking number already exists, or the shipment tracking limit was exceeded).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object" }, "msg": { "type": "string", "example": "Error while creating tracking number" } } } } } }, "401": { "description": "Unauthorized. Invalid or missing authentication token." }, "403": { "description": "Forbidden. Token cannot manage tracking for this shipment." }, "404": { "description": "Shipment not found, not awarded, or archived." } }, "x-displayName": "Add tracking number" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "security": [ { "TokenAuth": [] }, { "BearerAuth": [] } ] }