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.
Typically, 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.
Note This end-point only applies to Shippers
Request URI
POST https://pluto.cargobase.com/api/1/requests/create
Content-Type: application/json
Authentication: Token 'your_token_here'
Body message
Because we generate a full request and invite available forwarders, there are some mandatory fields that need to be taken into account.
The message body is constructed around 3 main object categories and 3 subcategories.
Some values are mandatory, others are optional
Main object categories
Category parameter
Purpose
Child object
organization
Organizational detail, such as Cost center or Reason code
good_items & good_customs_items
service
Details such as incoterms or freight modes
none
schedule
Details such as locations or timing
none
Body Sub-categories
Category parameter
Purpose
Parent object
good_items
Specification of individual handling units
organization
good_customs_items
Specification of commercial values or details of individual handling units
good_items
special_requirements
Specification of commercial values or details of individual handling units
good_items
organization values
Key
Value
Mandatory
Purpose
Parent object
location
STRING
MANDATORY
A reference to the 'location' the request is for, location references are shared by Cargobase
organization
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
quoting_deadline_date
STRING
MANDATORY
Quote deadline date (UTC time) in specified format YYYY-MM-DD
organization
quoting_deadline_time
STRING
MANDATORY
Quote deadline time of day (UTC time) in specified format HH:MM
organization
confirmation_date
STRING
MANDATORY
Confirmation time date (UTC time) in specified format YYYY-MM-DD
organization
confirmation_time
STRING
MANDATORY
Confirmation time of day (UTC time) in specified format HH:MM
organization
good_items
OBJECT
MANDATORY
see specification below
organization
title
STRING
No
Posted as title of the shipment for easy reference
organization
cost_center
STRING
No
Value of cost_center - can have custom label
organization
custom_field1
STRING
No
Value of custom_field1 - can have custom label
organization
custom_field1
STRING
No
Value of custom_field2 - can have custom label
organization
custom_longfield_01
STRING
No
Value of Custom_longfield_01, can have a custom label
organization
reason_code
STRING
No
Value of custom_field1 - can have custom label
organization
special_requirements
OBJECT
No
see specification below
organization
good_items
Each request can have 1 or multiple goods on the packing list. These goods are described in 'good_item'-objects.
A request can have multiple such objects.
Key
Value
Mandatory
Purpose
handling_unit
STRING
No
String of handling unit - see options below
units
INT
No
Quantity of items of this type
length
INT
No
Length in whole centimeters or inches
width
INT
No
Width in whole centimeters or inches
height
INT
No
Height in whole centimeters or inches
m_unit
STRING
No
Unit of measurement for LxWxH can be "cm" or "inch"
weight
INT
No
Weight in whole kgs or lbs
w_unit
STRING
No
Unit of measurement for weight can be "lbs" or "kg"
stackable
BOOLEAN
No
To indicate if unit is stackable
hazardous
BOOLEAN
No
To indicate if unit is hazardous
is_dangerous
BOOLEAN
No
To indicate if unit is classified as a dangerous good
dangerous_goods_value
STRING
No
Reference number of the DG class, see table below for potential values
container_type
STRING
No
Reference number of the container type, see table below for potential values
refridgerated_container
BOOLEAN
No
To identify if container should be refridgerated, in case of handling unit container
additional_information
STRING
No
Text description of additional information for this item
goods_customs_information
OBJECT
No
OBJECT containing customs information for this item
handling_unit options
Bag
Box
Carton
Case
Crate
Container
Pallet
Tube
NOTE Custom handling units are not supported at this moment.
Dangerous goods value
Value
Description
1
DG 1: Explosive substances and articles
2
DG 2: Gasses
3
DG 3: Flammable liquids
4
DG 4: Flammable solids
5
DG 5: Oxidising substances
6
DG 6: Toxic & Infectious substances
7
DG 7: Radioactive material
8
DG 8: Corrosives
9
DG 9: Miscellaneous
Container type value
Value
Description
1
20Ft Standard
2
20Ft Open top
3
20Ft Flatrack
4
20Ft Flatrack Collapsible
5
20Ft Platform
6
20Ft Refrigerated
7
20Ft Bulk
8
20Ft Tank
9
20Ft Ventilated
10
40Ft Standard
11
40Ft Open top
12
40Ft High-Cube
13
40Ft Flatrack
14
40Ft Flatrack collapsible
15
40Ft Platform
16
40Ft Refrigerated
17
45Ft High-Cube
18
Custom size
19
LCL
goods_customs_information
Each good item can contain multiple goods, these goods are described in the 'goods_customs_information' object.
A good item can have multiple such objects.
Key
Value
Purpose
value
INTEGER
Monetary value of product in this handling unit
currency_code
STRING
3-letter ISO code of currency of the value of the item
description
STRING
Description of item contents
hs_code
STRING
HS Code of the item
special_requirements
Each request can have special requirements, these are defined in the special_requirements object.
Each request can only have 1 special requirements object.
This object is not a mandatory object for most, however - for some it is; in those cases, all booleans mentioned below are expected.
Key
Value
Purpose
air_truck_required
BOOLEAN
Indication if this requirement is requested on the shipment
air_truck_additional_information
STRING
Additional description of this requirement
shock_tilt_required
BOOLEAN
Indication if this requirement is requested on the shipment
shock_tilt_additional_information
STRING
Additional description of this requirement
unique_handling_required
BOOLEAN
Indication if this requirement is requested on the shipment
unique_handling_additional_information
STRING
Additional description of this requirement
chemical_magnetic_concerns
BOOLEAN
Indication if this requirement is requested on the shipment
chemical_magnetic_additional_information
STRING
Additional description of this requirement
unique_warehousing_required
BOOLEAN
Indication if this requirement is requested on the shipment
unique_warehousing_additional_information
STRING
Additional description of this requirement
special_transport_required
BOOLEAN
Indication if this requirement is requested on the shipment
special_transport_additional_information
STRING
Additional description of this requirement
special_provider_requirements
BOOLEAN
Indication if this requirement is requested on the shipment
special_provider_additional_information
STRING
Additional description of this requirement
special_lift_fixtures_required
BOOLEAN
Indication if this requirement is requested on the shipment
special_lift_fixtures_additional_information
STRING
Additional description of this requirement
service values
Key
Value
Mandatory
Purpose
Parent object
incoterm
STRING
MANDATORY
Requested incoterms - see possible options below
service
insurance
BOOLEAN
MANDATORY
To indicate if shipment insurance is requested
service
insurance_instructions
STRING
No
Descriptive text of your request, in case set to 'true'
service
service_requirement
MANDATORY
STRING
Indication of service requirement type - see options below
service
export_clearance
BOOLEAN
MANDATORY
Indication if Export clearance is requested and how - see Clearance options below
service
export_clearance_instructions
STRING
No
Descriptive text of your request, in case set to 'true'
service
transit_clearance
BOOLEAN
MANDATORY
Indication if Transit clearance is requested and how - see Clearance options below
service
transit_clearance_instructions
STRING
No
Descriptive text of your request, in case set to 'true'
service
import_clearance
BOOLEAN
MANDATORY
Indication if Import clearance is requested and how - see Clearance options below
service
import_clearance_instructions
STRING
No
Descriptive text of your request, in case set to 'true'
service
air_charter_invited
BOOLEAN
MANDATORY
To indicate if Air charter forwarders should be invited
service
next_flight_invited
BOOLEAN
MANDATORY
To indicate if Next flight out (NFO) forwarders should be invited
service
ocean_freight_invited
BOOLEAN
MANDATORY
To indicate if Ocean freight forwarders should be invited
service
rail_freight_invited
BOOLEAN
MANDATORY
To indicate if Rail freight forwarders should be invited
service
regular_air_freight_invited
BOOLEAN
MANDATORY
To indicate if Regular Air freight forwarders should be invited
service
road_freight_invited
BOOLEAN
MANDATORY
To indicate if Road freight forwarders should be invited
service
road_freight_type
BOOLEAN
MANDATORY
Specification of road freight type, see options below
service
Incoterm options
Value
Description
EXW
Ex Works
FCA
Free Carrier
CPT
Carriage Paid To
CIP
Carriage Insurance Paid to
DAT
Delivery At Terminal
DAT
Delivery At Place
DDP
Delivery Duty Paid
FAS
Free Along Ship
FOB
Free On Board
CFR
Cost and Freight
CIF
Cost, Insurance and Freight
Service requirement options
Value
Description
DTD
Door-to-Door
DTP
Door-to-Port
PTD
Port-to-Door
PTP
Port-to-Port
Clearance options
Value
Description
1
Maby requested, to be clarified in description
2
Will be arrange by shipper, to be clarified in accompanying description
3
Provider is requested to arrange, to be clarified in accompanying description
Road freight options
Value
Description
FTL
Full-truck load
LTL
Less than Truck Load
GROUND_EXPEDITE
Ground Expedite
SPECIALIZED
Specialized - Car haulers, flat-beds, dump truck
MULTI_STOP
Multi-stop
schedule values
Key
Value
Mandatory
Purpose
Parent object
pickup_airport_code
STRING
CONDITIONAL
IATA Airport code, if identified otherwise null
schedule
pickup_airport
STRING
CONDITIONAL
Airport Name, if identified otherwise null
schedule
pickup_seaport_code
STRING
CONDITIONAL
Seaport code (UN/LOCODE), if identified otherwise null
schedule
pickup_seaport
TYPE
CONDITIONAL
Seaport name, if identified otherwise null
schedule
pickup_street
STRING
MANDATORY
Pickup street address
schedule
pickup_address_name
STRING
MANDATORY
Pickup company name
schedule
pickup_state
STRING
CONDITIONAL
The state/province in case of Canada, Mexico or USA, see below for value options
schedule
pickup_zipcode
STRING
MANDATORY
The pickup postal code
schedule
pickup_city
STRING
MANDATORY
The pickup city
schedule
pickup_country
STRING
MANDATORY
The pickup country, see below for value options
schedule
pickup_date
TIMESTAMP
MANDATORY
Requested pickup date (local time), format YYYY-MM-DD
schedule
pickup_time
TIMESTAMP
MANDATORY
Requested pickup time (local time), format HH:MM
schedule
pickup_time_type
INTEGER
MANDATORY
Requested pickup type can be 1=Regularor 2=Between
schedule
pickup_end_date
TIMESTAMP
No
Requested pickup end date (local time), in case of pickup_time_type 2
schedule
pickup_end_time
TIMESTAMP
No
Requested pickup end time (local time), in case of pickup_time_type 2
schedule
pickup_hours_start
TIMESTAMP
No
If Shipper indicated pickup location opening hours format: HH:MM
schedule
pickup_hours_end
TYPE
No
If Shipper indicated pickup location closing hours format: HH:MM
schedule
pickup_notes
STRING
No
Additional pickup notes
schedule
pickup_contact_name
STRING
MANDATORY
Name of contact person at pickup location
schedule
pickup_contact_phone
STRING
MANDATORY
Phone number of contact person at pickup location
schedule
pickup_contact_email
STRING
MANDATORY
Email of contact person at pickup location
schedule
pickup_address_type
STRING
No
Can be Address, Seaport or Airport
schedule
stop1_airport
STRING
CONDITIONAL
Airport Name, if identified otherwise null
schedule
stop1_seaport_code
STRING
CONDITIONAL
Seaport code, if identified otherwise null
schedule
stop1_seaport
TYPE
CONDITIONAL
Seaport name, if identified otherwise null
schedule
stop1_street
STRING
MANDATORY
Delivery street address
schedule
stop1_address_name
STRING
MANDATORY
Delivery company name
schedule
stop1_state
STRING
CONDITIONAL
The state/province in case of Canada, Mexico or USA, see below for value options
schedule
stop1_zipcode
STRING
MANDATORY
The delivery postal code
schedule
stop1_city
STRING
MANDATORY
The delivery city
schedule
stop1_country
STRING
MANDATORY
The delivery country, see below for value options
schedule
stop1_date
TIMESTAMP
MANDATORY
Requested delivery date (local time), format YYYY-MM-DD
schedule
stop1_time
TIMESTAMP
MANDATORY
Requested delivery time (local time), format HH:MM
schedule
stop1_time_type
INTEGER
No
Requested delivery type can be 1=Regularor 2=Between
schedule
stop1_end_date
TIMESTAMP
No
Requested delivery end date (local time), in case of stop1_time_type 2
schedule
stop1_end_time
TIMESTAMP
No
Requested delivery end time (local time), in case of stop1_time_type 2
schedule
stop1_hours_start
TIMESTAMP
No
If Shipper indicated delivery location opening hours format: HH:MM
schedule
stop1_hours_end
TYPE
No
If Shipper indicated delivery location closing hours format: HH:MM
schedule
stop1_notes
STRING
No
Additional delivery notes
schedule
stop1_contact_name
STRING
MANDATORY
Name of contact person at delivery location
schedule
stop1_contact_phone
STRING
MANDATORY
Phone number of contact person at delivery location
schedule
stop1_contact_email
STRING
MANDATORY
Email of contact person at delivery location
schedule
stop1_address_type
STRING
No
Can be Address, Seaport or Airport
schedule
Country values
Countries 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.
A full list of ISO codes per country can be found here Wikipedia link
State / province values
At 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.
Status codes
Status
Description
Resolution
201
Created
"Request created with Shipment number S71229654"
403
Forbidden
check Authentication token
In case of a successful POST your response will contain the details that were posted, as confirmation.
