The Request Draft end-point can be used to generate draft quote requests on Cargobase.
Typically this end-point is used to connect to your ERP or ordering system to prevent a duplication of effort. In most cases, not all values or validations can be mapped directly, so whenever a draft request is pushed, you will need to validate your input on the Cargobase platform. This should take you no longer than 2 minutes.
Note This end-point only applies to Shippers
Request URI
POST https://pluto.cargobase.com/api/1/requests/draft
Content-Type: application/json
Authorization: Token your_token_here
Known issues
Currently 'special_requirements' are a mandatory object for creating requests, even if this option is disabled for the shipper.
Body message
Because we generate your request as a draft, there are no minimum values, besides the Authorization and content-type headers. The more information your provide however, the quicker the validation process on the Cargobase platform is.
The message body is constructed around 3 main object categories and 3 subcategories.
Each category is mandatory in the request, specific values are not.
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
Purpose
Parent object
title
STRING
Posted as title of the shipment for easy reference
organization
cost_center
STRING
Value of cost_center - can have custom label
organization
custom_field1
STRING
Value of custom_field1 - can have custom label
organization
custom_field2
STRING
Value of custom_field2 - can have custom label
organization
custom_longfield_01
STRING
Value of custom_longfield_01 - can have custom label
organization
reason_code
STRING
Value of custom_field1 - can have custom label
organization
quoting_deadline_date
STRING
Quote deadline date (UTC time) in specified format YYYY-MM-DD
organization
quoting_deadline_time
STRING
Quote deadline time of day (UTC time) in specified format HH:MM
organization
confirmation_date
STRING
Confirmation time date (UTC time) in specified format YYYY-MM-DD
organization
confirmation_time
STRING
Confirmation time of day (UTC time) in specified format HH:MM
organization
good_items
OBJECT
see specification below
organization
special_requirements
OBJECT
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
Purpose
handling_unit
STRING
String of handling unit - see options below
units
INT
Quantity of items of this type
length
INT
Length in whole centimeters or inches
width
INT
Width in whole centimeters or inches
height
INT
Height in whole centimeters or inches
m_unit
STRING
Unit of measurement for LxWxH can be "cm" or "inch"
weight
INT
Weight in whole kgs or lbs
w_unit
STRING
Unit of measurement for weight can be "lbs" or "kg"
stackable
BOOLEAN
To indicate if unit is stackable
hazardous
BOOLEAN
To indicate if unit is hazardous
is_dangerous
BOOLEAN
To indicate if unit is classified as a dangerous good
dangerous_goods_value
STRING
Reference number of the DG class, see table below for potential values
container_type
STRING
Reference number of the container type, see table below for potential values
refridgerated_container
BOOLEAN
To identify if container should be refridgerated, in case of handling unit container
additional_information
STRING
Text description of additional information for this item
goods_customs_information
OBJECT
OBJECT containing customs information for this item
handling_unit options
Bag
Box
Carton
Case
Crate
Container
Pallet
Tube
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.
Currently this object is a mandatory part of the request, even if special requirements are not part of the shipper settings.
This is a known issue
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
Purpose
Parent object
incoterm
STRING
Requested incoterms - see possible options below
service
insurance
BOOLEAN
To indicate if shipment insurance is requested
service
insurance_instructions
STRING
Descriptive text of your request, in case set to 'true'
service
service_requirement
STRING
Indication of service requirement type - see options below
service
export_clearance
INTEGER
Indication if Export clearance is requested and how - see Clearance options below
service
export_clearance_instructions
STRING
Descriptive text of your request, in case set to 'true'
service
transit_clearance
INTEGER
Indication if Transit clearance is requested and how - see Clearance options below
service
transit_clearance_instructions
STRING
Descriptive text of your request, in case set to 'true'
service
import_clearance
INTEGER
Indication if Import clearance is requested and how - see Clearance options below
service
import_clearance_instructions
STRING
Descriptive text of your request, in case set to 'true'
service
air_charter_invited
BOOLEAN
To indicate if Air charter forwarders should be invited
service
next_flight_invited
BOOLEAN
To indicate if Next flight out (NFO) forwarders should be invited
service
ocean_freight_invited
BOOLEAN
To indicate if Ocean freight forwarders should be invited
service
rail_freight_invited
BOOLEAN
To indicate if Rail freight forwarders should be invited
service
regular_air_freight_invited
BOOLEAN
To indicate if Regular Air freight forwarders should be invited
service
road_freight_invited
BOOLEAN
To indicate if Road freight forwarders should be invited
service
road_freight_type
STRING
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
Maybe 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
Purpose
Parent object
pickup_airport_code
STRING
IATA Airport code, if identified otherwise null
schedule
pickup_airport
STRING
Airport Name, if identified otherwise null
schedule
pickup_seaport_code
STRING
Seaport code, if identified otherwise null
schedule
pickup_seaport
TYPE
Seaport name, if identified otherwise null
schedule
pickup_street
STRING
Pickup street address
schedule
pickup_address_name
STRING
Pickup company name
schedule
pickup_state
STRING
CONDITIONAL
The state/province in case of Canada, Mexico or USA, see below for value options
pickup_zipcode
STRING
The pickup postal code
schedule
pickup_city
STRING
The pickup city
schedule
pickup_country
STRING
The pickup country
schedule
pickup_country
STRING
MANDATORY
The pickup country, see below for value options
pickup_date
TIMESTAMP
Requested pickup date, format YYYY-MM-DD
schedule
pickup_time
TIMESTAMP
Requested pickup time, format HH:MM
schedule
pickup_time_type
INTEGER
Requested pickup type can be 1=Regularor 2=Between
schedule
pickup_end_date
TIMESTAMP
Requested pickup end date, in case of pickup_time_type 2
schedule
pickup_end_time
TIMESTAMP
Requested pickup end time, in case of pickup_time_type 2
schedule
pickup_hours_start
TIMESTAMP
If Shipper indicated pickup location opening hours format: HH:MM
schedule
pickup_hours_end
TYPE
If Shipper indicated pickup location closing hours format: HH:MM
schedule
pickup_notes
STRING
Additional pickup notes
schedule
pickup_contact_name
STRING
Name of contact person at pickup location
schedule
pickup_contact_phone
STRING
Phone number of contact person at pickup location
schedule
pickup_contact_email
STRING
Email of contact person at pickup location
schedule
pickup_address_type
STRING
Can be Address, Seaport or Airport
schedule
stop1_airport
STRING
Airport Name, if identified otherwise null
schedule
stop1_seaport_code
STRING
Seaport code, if identified otherwise null
schedule
stop1_seaport
TYPE
Seaport name, if identified otherwise null
schedule
stop1_street
STRING
Delivery street address
schedule
stop1_address_name
STRING
Delivery company name
schedule
stop1_state
STRING
CONDITIONAL
The state/province in case of Canada, Mexico or USA, see below for value options
stop1_zipcode
STRING
The delivery postal code
schedule
stop1_city
STRING
The delivery city
schedule
stop1_country
STRING
MANDATORY
The delivery country, see below for value options
stop1_date
TIMESTAMP
Requested delivery date, format YYYY-MM-DD
schedule
stop1_time
TIMESTAMP
Requested delivery time, format HH:MM
schedule
stop1_time_type
INTEGER
Requested delivery type can be 1=Regularor 2=Between
schedule
stop1_end_date
TIMESTAMP
Requested delivery end date, in case of stop1_time_type 2
schedule
stop1_end_time
TIMESTAMP
Requested delivery end time, in case of stop1_time_type 2
schedule
stop1_hours_start
TIMESTAMP
If Shipper indicated delivery location opening hours format: HH:MM
schedule
stop1_hours_end
TYPE
If Shipper indicated delivery location closing hours format: HH:MM
schedule
stop1_notes
STRING
Additional delivery notes
schedule
stop1_contact_name
STRING
Name of contact person at delivery location
schedule
stop1_contact_phone
STRING
Phone number of contact person at delivery location
schedule
stop1_contact_email
STRING
Email of contact person at delivery location
schedule
stop1_address_type
STRING
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
Your draft has been posted
403
Forbidden
check Authentication token
In case of a successful POST your response will contain the details that were posted, as confirmation.
Language
Credentials
http
Response
Click Try It! to start a request and see the response here!
